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Ho}N to Use This Manual 

This document contains tlie following chapters: 
Chapter 1 Introduction 

Introduces the TIGA-340 Interface, its features and architecture. 
Ciiapter 2 Getting Started 

Contains instructions to install TIGA on a PC and to run a demonstration pro- 
gram. 

Chapter 3 TIGA Application Interface 

Describes the application interface and lists all TIGA primitive instructions. 
Chapter 4 Extensibility Through the User Library 

Describes how to extend TIGA by adding your own functions; also describes 
the command processing entry points of the communication driver. 

Appendix A TIGA Data Structures 

Describes the data structures used in TIGA. 

Appendix B Graphics Output Primitives 

Describes the assumptions made and conventions adopted for the drawing 
primitives. 

Appendix C TIGA Reserved Symbols 

Describes the function names reserved for internal use of TIGA. 
Appendix D Porting Guide 

Describes the procedure to port TIGA to any TMS340-based graphics 
board. 

Appendix E Debugger Support for TIGA 

Contains the initial TIGA debugger routines. 

Appendix F Glossary 

Contains the definitions of TIG A-specif ic and TIGA-related terms and acro- 
nyms. 
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Related Documentation 

The following TMS3401 documents are available from Texas Instruments: 

Q TheTMS34010 C Compiler User's Guide (literature number 
SPVU005) tells you how to use the TMS3401 C Compiler. This C com- 
piler accepts standard Kernighan and Ritchie C source code and pro- 
duces TMS34010 assembly language source code. We suggest that 
you use The C Programming Languagebook (by Brian W. Kernighan 
and Dennis M. Ritchie) as a companion to the TMS34010 C Compiler 
User's Guide. 

^ The TMS34010 Assembly Language Tools User's Guide (literature 
number SP VU004) describes common object file format, assembler di- 
rectives, macro language, and assembler, linker, archiver, simulator, 
and object format converter operation. 

Q The TMS34010 Data Sheet (literature number SPVS002) contains the 
recommended operating conditions, electrical specifications, and tim- 
ing characteristics of the TMS34010. 

Q The TMS34010 User's Guide (literature number SPVU001 ) discusses 
hardware aspects of the TMS34010, such as pin functions, architec- 
ture, stack operation, and interfaces, and contains the TMS34010 in- 
struction set. 

You may also find the following documentation useful: 

Kernighan, Brian, and Dennis Ritchie. The C Programming Language. En- 
glewood Cliffs, New Jersey: Prentice-Hall, 1978. 

Newman W.M., and R. F. Sproull. Principles of Interactive Computer Graph- 
ics. 2nd ed. New York: McGraw-Hill, 1 979. 
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Style and Symbol Conventions 

This document uses the following conventions: 

Q TIGA primitive function names are shown in bold face lettering. 

Q Parameters for the TIGA functions are shown in program font (Couri- 
er). For example, the TIGA function drawjine has parameters xi, 

yl, x2, y2. 

i^ Program examples and filenames (example: tigalnk . exe) are shown 
in program font. Here is an example program: 

finclude <tiga.h> 

main ( ) 
{ 

short module; 

/* initialize TIGA */ 

if (!set_videomode(TIGA, INIT) ) 

{ 

printf ("Fatal Error - TIGA not installed\n") ; 

exit(O); 
} 

/* attempt to install module */ 
if ((module = install_rlm ( "EXAMPLE" ) ) < ) 
{ 

printf ("Fatal Error - couldn't install Example RLM\n") ; 
printf ("Error code = %d\n", module); 

exit(O); 
} 
/* code to invoke the module functions */ 

set videomode (PREVIOUS, INIT); 



In syntax descriptions, the instruction, command, or directive is in a 
bold face font with parameters in Itaiics. Portions of a syntax in bold 
face (including quote marks) should be entered as shown. Portions of 
a syntax in italics describe the type of information that you provide. 
Square brackets identify optional information: 



mg2tiga MGfont TIGA font ["facename"] 
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This user's guide describes tiie TiGA-340™ (Texas Instruments Graphics 
Architecture), a software interface that standardizes communication be- 
tween application software and all TMS340 family-based hardware for IBM- 
compatible personal computers. TIGA divides tasks between the TMS340 
processor and the 80x86 host to improve application performance. 

Section Page 

1.1 Developer's Kits 1-2 

1.2 Features 1-3 

1 .3 Architecture 1-4 

1 .4 Extensibility 1-6 

The TIGA interface standard simplifies the development of portable applica- 
tions and application drivers to the diverse range of TMS340-based sys- 
tems. TIGA can be extended so that software developers can customize 
TIGA-340 to a specific application and so that hardware developers can pro- 
vide a simple Interface to specific target features. 

TIGA contains a low-level communication Interface designed so that other 
standards such as MS-Windows, Presentation Manager (PM), DGIS, GEM, 
CGI, and PGA, can run through the interface with no performance penalty. 
Essentially, TIGA replaces custom communication routines in other soft- 
ware interfaces with a single standard set of host-to-TMS340 communica- 
tion routines. 
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1.1 Developer's Kits 



This user's guide supports two basic TIGA developer's kits, the Driver De- 
veloper's Kit (DDK) and the Software Porting Kit (SPK). A third develop- 
er's kit, the Software Developer's Kit (SDK), includes the DDK as a sub- 
set. 

Q DDK: The Driver Developer's Kit (Tl part number TMS340 DDK-PC) 

The TIGA-340 DDK provides software designers with the tools required 
to produce TIGA-compatible applications. These tools include a copy of 
the TIGA-340 interface, which runs on the TMS3401 Software Devel- 
opment Board, a user's guide, utilities, an AutoCAD release 9 sample 
driver, and several TIGA-compatible example programs. With these 
tools a programmer can modify existing applications to run with the 
TIGA-340 interface or develop new TIGA-compatible applications. The 
development of TIGA-compatible applications is easy because the 
tools in the kit are designed to work with the industry-standard Microsoft 
C development tools and debugging environments. 

Q SPK: The Software Porting Kit (Tl part number TMS340SPK-PC) 

The SPK helps hardware manufacturers and software operating envi- 
ronment developers make their TMS340-based systems TIGA-com- 
patible.The SDK, described below, is included as a subset to this kit. 

The SPK contains everything in the DDK plus all source code required 
to port the TIGA-340 interface to any TMS340 system, allowing all 
TIGA-compatible applications to run on that system. TMS340 source 
and 8086 object codes for a TIGA-compatible Windows/286 driver are 
also included. 

□i SDK: The Software Developer's Kit (Tl part number 
TMS340SDK-PC) 

The SDK is for those who want to develop direct TMS34010 code or 
custom, downloadable extensions to TIGA. In addition to the DDK, it in- 
cludes Tl's TMS3401 C Compiler, Assembler, Bitmap Font, and Math/ 
Graphics source code libraries. 
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1.2 Features 



These are the key application-related features of the TIGA interface stan- 
dard: 



Applications run faster 



Easy to use 



Extensible 



Hardware independent 



TIGA-340 provides the application writer with a 
dual-processor environment. This enables the 
tasks in the application to be run in parallel by 
partitioning them between the host and the 
TMS340 processors. The TIGA-340 interface is 
optimized to provide high-speed com- 
munications between the host and the TMS340 
family processors and to minimize the 
overhead in the processing of TIGA com- 
mands. 

TIGA-340 provides applications with a base set 
of graphics primitives, with all the support 
required for the graphics subsystem. TIGA-340 
is compatible with the Microsoft C environment, 
and Microsoft development tools can be used 
for debugging the application. 

Where an application requires graphics 
functions that are not available in the TIGA base 
set of primitives, the application writer can 
develop user-extended primitives using 
TMS340 C, assembly language, or a mixture of 
the two. These user-extended primitives can be 
downloaded at runtime during the application 
initialization. 

Inquiry functions are provided that enable the 
application to determine the resolution, pixel 
size, etc., of the graphics subsystem and to 
adapt itself to the board on which it runs. 
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1.3 Architecture 

Figure 1-1 shows a block diagram of the TIGA-340 interface, illustrating the 
communication between the host routines and the TMS340 family proces- 
sor routines. 

As Figure 1-1 shows, the TIGA standard consists of four components: 

1) Application Interface (Al) 

2) Communication Driver (CD) 

3) Graphics Manager (GM) 

4) TIGA Extensions 

Figure 1-1. Block Diagram 
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The Application Interface (Al) is linked in with a TIGA Application. The Al 
consists of header files that reference TIGA function and type definitions, 
which may be used in the application, and of a library that the application 
links to when it is created. The Al does not actually contain the routines that 
Interface to the TMS340 processor; these routines are contained in the com- 
munication driver. 

The Communication Driver (CD) Is a Terminate-and-Stay-Resident (TSR) 
program that runs on a host PC. The CD Is specific to the TMS340 board 
and is ported to it by a board manufacturer. A manufacturer ships the CD 
with the board; the CD is in af ile called tigacd . exe . This file can be invoked 
by the user directly from the command line or placed in the autoexec . bat 
file to be executed at startup. The CD contains the functions used to commu- 
nicate between the host and the TMS340 board. These functions are In- 
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voked via calls in the A! made by the application. These communication 
functions take care of the host side hardware-dependent portion of TIGA, 
considering such things as whether the TMS340 board is memory-mapped 
or l/0-mapped. 

The Graphics Manager (GM) is a program that runs on the TMS340 board 
and is specific to the board that it resides on. It consists of a command ex- 
ecutive that handles the TMS340 side of the communications with the host, 
and a set of standard primitives that perform graphics operations. The GM 
typically resides in RAM on the board (although this is not a requirement) 
and therefore must be loaded onto the board after power-up. There are two 
mechanisms for doing this. TIGA comes with a linking loader tigalnk . exe, 
which loads the GM explicitly by invoking it with the -ix (Load and eXecute) 
flag. Alternately, the communication driver routines can sense whether the 
GM is running; when the application makes its first Al call, it detects if Al is 
not running and loads it. 

TIGA contains a set of primitives to perform a wide range of graphics opera- 
tions.The set of primitives can be extended by downloading the application 
functions onto the TMS340 system. These downloaded functions may be 
written using either the TMS340 C or assembly languages. Downloading 
functions can decrease the host-TMS340 processor communications time 
and thus improve the performance of the application. 

The host application invokes most of the TIGA functions on the TMS340 
processor by downloading the parameters of the function, along with acom- 
mand number, into one of several communication buffers. The command 
number is an identif ierfor the function to be executed. The command execu- 
tive, which forms part of the GM, determines which function is to be invoked 
and calls it with the parameters that have been passed to it. Because there 
are several buffers, the host downloads data into one buffer while the 
TMS340 is executing data from another. This parallelism produces signifi- 
cant speed improvement over the host performing the graphics manipula- 
tion directly. 
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1.4 Extensibility 

Graphics standards before TIGA limited the software developer by provid- 
ing a fixed set of graphics drawing primitives. In the rapidly changing graph- 
ics market, afixed set of primitives is unacceptable. During the development 
of the TIGA graphics interface, incorporating extensibility into the standard 
was a major design goal. 

TIGA's functionality can be extended by adding or manipulating its user li- 
brary collection of C-callable routines. Figure 1-2 shows the configuration 
options for TIGA primitives. 

Figure 1-2. Primitive Configuration Options 
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TIGA-compatible applications can be developed using the base set of primi- 
tives provided by the TIGA-340 Interface (as shown in the left hand side of 
Figure 1 -2). These TIGA primitives include the core primitives, which are al- 
ways available to the application, and the TIGA extended primitives, which 
are loaded if the application requires them.The set of graphics primitives 
and the performance of the TMS340 processor give many applications an 
acceptable level of graphics performance. However, an application has the 
ability to improve this performance by downloading user-extended primi- 
tives. The user-extended primitives can be downloaded to be used in addi- 
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tion to or instead of the TIGA extended primitives (as siiown on the right- 
hand side of Figure 1-2). 

A hardware developer can implement the same concept of adding primi- 
tives. For example, if the developer of a TMS340-based graphics system 
incorporates hardware in addition to the TMS340 processor, access to this 
hardware can be provided through the TIGA interface. The access is ac- 
complished by developing a set of user-extended primitives which use the 
additional hardware functionality. Thus, the TIGA-340 interface provides a 
standard programming platform for the software written by the hardware de- 
veloper using these user-extended primitives. 
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This chapter contains instructions for installing TIGA on your system: 

Section Page 

2.1 System Requirements 2-2 

2.2 installing TIGA on your System 2-4 

2.3 Modifying the Autoexec and the Environment 2-9 

2.4 Running the TIGA Driver 2-10 

2.5 The TIGA Environment Variable 2-11 

2.6 TIGA Utility Programs 2-12 

2.7 Required Non-TIGA Development Utility Programs 2-17 

2.8 TIGA Syntax and Programming Examples 2-18 
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2.1 System Requirements 

To ensure proper installation and operation of TIGA, your system must meet 
certain software and iiardware minimum requirements. Consult the follow- 
ing sections for a list of these requirements, depending on the TIGA kit you 
are installing. 

2.1 .1 TIGA Driver Developer's Kit (DDK) System Requirements 

Q IBM PC, XT, AT or 1 00% compatible (hard disk required) 

Q 640KRAM 

Qi LIM expanded memory plus expanded memory manager (for AD! driver 
only) 

Ul Texas Instruments TMS3401 Software Development Board (SDB) 

Ui MS-DOS or PC-DOS, version 2.13 or above 

□i Microsoft Macro Assembler, version 5.0 or above (if developing as- 
sembler-based applications/drivers) 

I^ Microsoft C Compiler, version 5.0 or above (if developing C applica- 
tions) 

Q TMS34010 C Compiler and assembly-language tools, version 3.0 or 
above (if writing user-extended functions) 

I I 

Note: 

The current version of TIGA supplied with the DDK is designed to run only 
on aTexas Instruments software development board (SDB). Pricing and or- 
dering information for the SDB is available from your local Texas Instru- 
ments Sales Office. 



2.1 .2 TIGA Software Porting Kit (SPK) System Requirements 

Q IBM PC.XT.ATor 100% compatible (hard disk required) 

Q 640KRAM 

Qi LIM expanded memory plus expanded memory manager (for AD! driver 
only) 

Ql Texas Instruments TMS34010 Software Development Board (SDB) 
(Only if you are not porting TIGA to a different board) 

Q MS-DOS or PC-DOS, version 2.13 or above 
2-2 Getting Started 



«!i»l!IMi8lll«mSRMHS«li»fSttt»»»^ 



System Requirements 



Q Microsoft Macro Assembler, version 5.0 or above 

Ql Microsoft C Compiler, version 5.0 or above (if developing C applica- 
tions) 

Qk TMS34010 C Compiler and assembly-language tools, version 3.0 or 
above (if writing user extended functions and/or if porting TIGA to a dif- 
ferent board) 

Note: 

The current version of TIGA supplied with the SPK is designed to run on 
a Texas Instruments software development board. However, all software 
necessary to port TIGA to a different TMS340 board is included in in the 
SPK. Consult Appendix D for information on how to port TIGA to a different 
TMS340 board. 



2-3 



Installing TIGA on your System 

2.2 Installing TIGA on Your System 



Note: 

If you have an earlier version of TIGA on your system, be aware that the 
TIGA installation procedure overwrites same-named files in the tiga and 
tigapgms directories. For this reason, files of previous versions of TIGA 
should be backed up, if needed, before proceeding with the new TIGA in- 
stallation. 



Both the TIGA DDK and SPK kits have an automated installation program 
to aid in installing TIGA on your system. In general, the installation proce- 
dure for the DDK and the SPK are the same. 

The DDK package is a subset of the SPK; the SPK package contains all 
of the files in the DDK plus additional files required for porting purposes. 
Therefore, if you have both the DDK and the SPK packages, install only the 
SPK on your system. 

Follow these instructions to install your TIGA kit: 

Step 1 : Place disk #1 (DDK #1 or SPK #1 ) of your TIGA kit into drive A: 

Step 2: If A: is not your current drive, enter a : Q at the MS-DOS prompt. 

Step 3: Make sure you are at the root directory of A:. If you are not sure, 
enter cd\ Q at the MS-DOS prompt. 

Step 4: Enter setup drive: H where cfr/Ve; designates your destination 
drive (hard disk). For example, if you want to install TIGA on your 
C: hard disk, enter setup c: B . 

Step 5: Follow the instructions displayed on the screen to complete instal- 
lation. 

During installation, you have the option of installing a collection of TIGA- 
compatible examples and demonstrations. It is recommended that these 
examples be installed because they are referenced as coding examples in 
this guide. 

The installation of your TIGA kit creates a number of subdirectories on your 
destination drive. Consult one of the following two sections (depending on 
the TIGA kit you installed) for information describing these subdirectories 
and the files contained within them. 
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2.2.1 Driver Developer's Kit (DDK) Subdirectories 

Installing the DDK on your system creates the following subdirectories: 



Subdirectory 

\tiga 

\tiga\ai 

\tiga\gm\extprims 
\tiga\include 
\tigapgms 



Description 

TIGA root directory, TIGA drivers, system files, and 

utility programs 

Application interface library 

Extended primitives source code archive 

Include files 

TIGA compatible examples and demonstrations 

(see Section 2.2.3 for more information) 

The \tiga\gm\extprims directory Contains the self-extracting archive file 
extprims.exe. Thls archive Contains source for every extended function 
available within TIGA. It enables you to choose the extended functions you 
need, link them with your specific user extensions, and create a custom 
TIGA dynamic load module with the TMS340 functions that your application 
or driver requires. To unarchive the source files contained in this archive, en- 
ter extprims Q from within this directory. 



2.2.2 Software Porting Kit (SPK) Subdirectories 

Installing the DDK on your system creates the following subdirectories: 



Subdirectory 

\tiga 

\tiga\ai 

\tiga\cd 

\tiga\gm 

\tiga\gm\corprims 

\tiga\gm\extprims 

\tiga\gin\sdb 

\tiga\include 

\tigapgms 



Description 

TIGA root directory, TIGA drivers, system 
files, and utility programs 
Application interface library and source 
TIGA communication driver source 
TIGA graphics manager root directory 
TIGA graphics manager core primitives 
TIGA graphics manager extended primitives 
TIGA graphics manager SDB specific files 
Include files 

TIGA compatible examples and demonstrations 
(see Section 2.2.3 for more information) 
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2.2.3 TIGA Demonstrations and Example Subdirectories 

During installation, you have the option of installing a collection of TIGA 
compatible demonstrations and examples. When installed, the following di- 
rectories are created on the destination drive: 

\tigapgms TIGA Compatible examples and demonstrations 

\tigapgms\adi TIGA compatible AutoCAD example driver 

\tigapgms\asmtst Assembly language application example 

\tigapgms\baii Interrupt example using graphics 

\tigapgms\ciock Downloaded Interrupt function example 

\tigapgms\curves Floating-point example 

\tigapgms\exampies Examples Supplied in Chapter 3 of this guide. 

\tigapgms\f lysim 3-D flying simulator example 

\tigapgms\stars Downloaded function example 

\tigapgms\tests TIGA test SUite 

\tigapgms\tigademo Demonstrates many of TIGA's functions 

\tigapgms\tigamode Board mode query/initlallzation program 

\tigapgms\tigaiogo Demonstrates fixed-point math operations 

\tigapgms\windows TIGA-compatible MS-Windows driver (SPK only) 

Each subdirectory contains a readme. ist file, complete source, and a 
make file to rebuild that particular demonstration. Consult the readme . 1st 
file for a description of the demonstration and rebuilding instructions. 

If you opted not to loadthe TIGA examples during the initial TIGA kit installa- 
tion, you can install the examples and demonstrations at any time, following 
the installation instructions outlined on page 2-4. Simply insert program 
disk #1 into drive A: instead of the DDK or SPK disk #1 as directed in step 
1 . Continue installation as described. 

2.2.4 Running a TIGA Demonstration 

After installing TIGA on your system, you can run any of the supplied dem- 
onstration programs. One such program, tigademo, is a free-running dem- 
onstration of TIGA's graphics primitives. The following instructions outline 

how to run tigademo: 

1 ) At the MS-DOS prompt, enter 
set path=c:\tiga D^ 

This provides access to TIGA's DOS commands from any directory. 

2) Enter 

set TIGAs-mc:\tiga |^ 

This Informs TIGA to look in the c:\tiga directory for TIGA-specific 
runtime files. 
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3) Enter 

cd \tigapgms\tigademo [pjHj 

This directory contains the tigademo program. 

4) Enter 

tigacd ^^ 

This loads the TIGA communication driver (CD). The CD provides the 
communication interface between a TIGA application and the target 
TMS340-based board. Once loaded, the CD remains resident in 
memory and requires reloading only after rebooting your system. 

5) Finally, enter 

tigademo []^ 

This executes tigademo. 

You can run any of the other supplied examples in a similar manner. 

I 
Note: 

Because the DDK/SPK is shipped with a Tl software development board 
(SDB) version of TIGA, you must have an SDB in your system (or have a 
version of TIGA compatible with your TMS340-board) before running any 
of the supplied examples. 
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2.2.5 TIGA Include Files 



The directory \tiga\inciude contains include files used in the TIGA source 
code itself and when writing TIGA applications. These include files are di- 
vided in two groups: those designed to run on the host processor and those 
designed to run on the TMS340 processor. They are also divided, as to 
whether they are used in C-source files or in assembler source files as fol- 
lows: 

□i Host-side include files 



Use when calling TIGA extended primitives 
Include always in a TIGA C program 
Include when using TIGA structure types 



■ C-source 

extend. h 

tiga.h 

typedefs.h 

■ Assembler source 

extend . inc Use when calling TIGA extended primitives. 
tiga . inc Include always in a TIGA assembly program. 

typedef s . inc Include when using TIGA structure types 

Qi TMS340-side include files 



C-source 

gspextnd.h 

gspglobs . h 

gspregs.h 
gsptiga.h 



Use for external declarations of all TIGA extended 

primitives 

Use for external declarations of all TIGA global 

variables 

Use for TMS340 register definitions 

Use for external declarations of all TIGA core 

primitives 

Include when using TIGA structure types 



gsptypes.h 

Assembler source 

gspextnd . inc Use for external declarations of all TIGA extended 

primitives 
gspglobs . inc Use for external declarations of all TIGA global 

variables 
gspregs . inc Use f or TMS340 register definitions 
gsptiga . inc Use for external declarations of all TIGA core 

primitives 
gsptypes . inc Include when using TIGA stnjcture types 
gspmac . lib Use for macro library 
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2.3 Modifying Autoexec and tlie Environment 

After installing your TIGA kit, you may wantto make afew modifications and/ 
or additions to your autoexec . bat or comparable batch file. Note that these 
instructions use C: to identify the hard disk drive. Replace C: with the drive 
designator where you Installed your particular TIGA kit: 

1 ) Append c : \t iga to the MS-DOS path: 

PATH=< existing PATH>; c; \tiga 

2) if you plan to develop TIGA-compatible applications in C or to rebuild 
any of the TIGA demos or the TIGA test suite, append 
c:\tiga\inciude to the Microsoft C compiler environment variable 

INCLUDE : 

set INCLUDE=<existing INCLUDE>; c; \tiga\in elude 

If you do not currently have an include environment variable in your 
autoexec . bat file, this Command adds it. 

3) If you have the TMS340 C Compiler and assembly-language tools in- 
stalled on your system, then append c: \tiga\inciude to the A_DIR 
and C_DI R environment variables: 

set A_DIR=<existing A_piR>; c: \tiga\include 
set C_DIR=<exi sting C_piR>! c: \tiga\include 

Again, if these environment variables currently do not exist, these com- 
mands add them. 

4) Add the following TIGA environment variable: 

set TIGA= -mc:\tiga 

See Section 2.5 on page 2-11 for a complete description of the TIGA 
environment variable. 

5) After modifying your autoexec .bat file, run it or reboot your PC. 
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2.4 Running the TIGA Driver 

To load TIGA: 



Enter tigacdlPH at the MS-DOS prompt. The command syntax for tigacd 
is: 



tigacd [flag] 



Available options: 

Flag Description 

-i Reinstalls the TSR. This option forces a new copy of the TIGA com- 
munication driver (CD) to be loaded in memory, thereby superseding 
any previously installed CD. Note that reinstalling the TSR with the -i 
option forces reloading of the TIGA graphics manager. 

-u Uninstalls the TSR. This option causes the previously Installed TIGA 
CD to be released from memory, disabling TIGA. To re-enable TIGA, 
enter: tigacd Q once again. 

-s Informs the TIGA CD to select operating modes valid for the SONY 
Multiscan monitor, rather than for the default monitor, the NEC Multi- 
sync monitor (SDB version only). 

After the TIGA CD is loaded, TIGA is ready to use; however, the TMS340 
side of TIGA has not yet been initialized. This is accomplished in one of the 
following ways: 

Q An application making a call to set_videomode(TIGA,INIT) checks 
whether the TIGA graphics manager (GM) is loaded and running on the 
TMS340 side. If so, both the host and TMS340 sides of TIGA are ready. 
If not, the GM is loaded, executed, and initialized prior to returning from 
the set__videomode function. 

Q Enter tigainic -ix from the MS-DOS command line after loading the 
TIGA CD, to force the TIGA GM to be loaded and executed. 

After loading the host and TMS340 sides of TIGA, your application Is free 
to call TIG As core primitives. 
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2.5 The TIGA Environment Variable 

TIGA uses the environment variable tiga to get information about the loca- 
tion of TIGA system files, dynamic load modules, and the desired interrupt 
level. Set the TIGA environment variable using the following syntax: 



set TIGA = [flag] [string] [flag] [string] 



Currently, TIGA recognizes three flags: 
Flag Description 

-m Specifies the path for TIGA system files 

-1 Specifies the path for TIGA dynamic load user modules 

-i Specifies the host interrupt level used by the TIGA communication 
driver 

When TIGA is initially installed, all TIGA system files are placed in the TIGA 
directory of the destination drive. Specify this path using the -mflag of the 
TIGA environment variable. 

Any dynamic load modules loaded from a TIGA application must be located 
in either: 

Q the current directory from which the TIGA application is called or 

Q the path specified by the -i flag in the TIGA environment variable. 

By default, TIGA's communication driver uses interrupt level Ox7F to com- 
municate with an application. Use the -i flag followed by the interrupt level 
(in hex format) in the TIGA environment variable to specify an alternate in- 
terrupt level. 

As an example, assume all TIGA system files are located in c : \tiga, user 
dynamic load modules are in d: \dim, and the desired interrupt level to use 
is 0x78. Set the corresponding TIGA environment variable: 

set TIGA=-/nc;\ tiga -ld:\dlm -10x78 ^M 
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2.6 TIGA Utility Programs 

The following TIGA utility programs are in TIGA's root directory \tiga to 
simplify porting and/or applications development: 

TIGA Utility Description 

cc . exe TMS340 tool Shell program, used in make files 

that rebuild TIGA's graphics manager 

citiga .bat Batch file to Compile and link a TIGA application 

mg2tiga . exe Utility to convert TMS340 math/graphics fonts to 
TIGA compatible fonts 

tigamode . exe Utility to query available modes and select default 
mode 

2.6.1 cc Utility 

This utility is used primarily by the TIGA graphics manager make files during 
rebuilding. It is also useful in compiling TMS340 C or assembling assembly- 
language code. 

cc is executed from the MS-DOS command line. Enter cc with no parame- 
ters to display usage instructions. Additional information on how to use the 
cc utility can be found in the TMS34010 Software Developer's Kit (SDK) 
User's Guide. 

2.6.2 citiga Batch File 

The citiga.bat batch file provides an easy way to compile and link a 
TIGA-compatible application (contained in a single C source file) to the 
TIGA application interface. It also supports symbolic debugging through Mi- 
crosoft's CodeView ® debugger. The syntax for citiga is: 



citiga [-ofj filename 



where -d is an option that specifies symbolic debug processing and file- 
name is the name of the C file to be processed. No extension should be spe- 
cified on the filename. 

I 
Note: 

The TIGA application interface library is independent of the Microsoft C 
model, thus, the citiga batch file does not specify any particular model and 
uses the default (small) model unless overridden. This can be done by set- 
ting the ci environment variable (consult the Microsoft C reference manual 
for details). 
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2.6.3 mg2tiga Utility 

The mg2tiga Utility converts fonts compatible with the TMS340 Math/ 
Graphics function librarytoaformat compatible with the TIGA text functions. 
The command line syntax for mg2tiga . exe is 



mg2tlga MG font TIGA font [ "facename"] 



where: 
MG font 



is a binary or COFF object image of a Math/Graphics compat- 
ible font. 



TIGA font is the filename under which the converted font is saved. 

facename is an optional name of the font (up to 31 characters long) en- 
closed within double-quotes. If this parameter is not specified 
on the command line, mg2tiga prompts you for it. 

Here is an example of converting the Tl Roman 18-point font from the math/ 
graphics font library to TIGA format. 

1 ) Locate the library that containsTI Roman fonts. As supplied, this library 
Is called ti_roman . lib and contains 1 2 fonts. A table of contents of 
this library: 

gspar -t ti_roman |piji{j 

GSP Archiver Version 3.00 

(c) Copyright 1985, 1988, Texas Instruments Incorporated 



FILE NAME 



SIZE 



DATE 



ti_romll 
ti_roml4 
ti_roml6 
ti_roml8 
ti_rom20 
ti_rom22 
ti_rom26 
ti_rom30 
ti_roin33 
ti_rom38 
ti_rom52 
ti rom78 



.obj 
.obj 
• obj 
.obj 
.obj 
.obj 
.obj 
.obj 
.obj 
.obj 
.obj 
.obj 



2358 

2744 

3130 

3258 

3898 

4538 

5432 

6330 

7098 

9658 

16698 

34878 



Thu 
Thu 
Thu 
Thu 
Thu 
Thu 
Thu 
Thu 
Thu 
Thu 
Thu 
Wed 



Jun 12 
Jun 12 
Jun 12 
Jun 12 
Jun 12 
Jun 12 
Jun 12 
Jun 12 
Jun 12 
Jun 12 
Jun 12 
Jun 18 



12:00; 
12:02; 
12:04; 
12:06; 
12:08; 
12:10; 
12:12; 
12:15; 
12:17; 
12:20; 
12:25; 
02:45; 



32 1986 
20 1986 
12 1986 
06 1986 
06 1986 
16 1986 
34 1986 
00 1986 
36 1986 
42 1986 
00 1986 
56 1986 



2) Extract the desired font, in this case ti_romi8 . obj. 

Example: gspar ac tijroman tij:oml8.^j |^ 

3) Now use mg2tiga to convert It to TIGA format. 
Example: mg2tiga tijcomlS.obj romanlS.fnt | 
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At this point, mg2tiga prompts you to enter a facename for tine font. 
Tliis facename can be up to 31 cliaracters long and siiould be the name 
of the font. 

Example: MGFL to TIGA font converter 

[ Converting: ti_roml8.obj -> romanlS.fnt ] 
Enter facename (31 chars max) : TI ROMAN |pm 

After you have entered the facename, mg2t iga displays the MG font header 
and then the new TIGA font header. A prompt to press Q follows each of 
these displays. After entering this information, the conversion is complete. 
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[ Old Font Header 

fonttype: 9000 
firstchar: 0000 
lastchar: OOff 
widemax: 0010 
kernmax: 0000 
nde scent: fffd 
charhigh: 0011 
owtloc: 046a 
ascent: OOOe 
descent: 0003 
leading: 0002 
rowwords: 0033 

[ Press return ]-> 

[ New Font Header 

magic: 8040 

length: 00000b 
facename: TI ROMAN 
first: 0000 
last: OOff 
maxwide: 0010 
maxkern: 0000 
charwide: 0000 
avgwide: 0008 
charhigh: 0011 
ascent: OOOe 
descent: 0003 
leading: 0002 
rowpitch: 00000330 
oPatnTbl: 00000250 
oLocTbl: 00003880 
oOwTbl: 000048a0 

[ Press return ]-> 



2-15 



TIGA Utility Programs 



2.6.4 tigamode Utility 



The tigamode Utility allows you to interrogate tiie operating modes of the 
TIGA-compatible graphics board in your system. It also enables you to se- 
lect a default mode for your board. For additional information and complete 
source for the tigamode utility, consult the \tigapgms\tigamode directory. 
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2.7 Non-TIGA Development Utility Programs 

TIG A development and/or porting relies heavily on the use of the Microsoft's 
Macro Assembler and/or Microsoft's C compiler packages. Specifically, 
both packages must be version 5.0 or later to ensure compatibility with 
TIGA. 

TIGA contains batch files that aid in rebuilding the TIGA communications 
driver and graphics manager (if you have the SPK), and batch files to com- 
pile and link your applications with the TIGA applications interface. These 
batch files use the following utility programs, which are bundled with the indi- 
cated Microsoft programming package: 

Utility program Description 

ci . exe Microsoft C compiler shell program 

lib . exe MS-DOS library manager, supplied with DOS 

link . exe MS-DOS linker, supplied with both packages 

make . exe Make Utility, Supplied with both packages 

These programs must be accessible from TIGA's batch files (via the PATH 
environment variable) to ensure proper operation. 
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2.8 TIGA Syntax and Programming Examples 

The definition of the TIGA syntax and the coding examples supplied In this 
guide are written primarily in Microsoft C, since Microsoft C is commonly 
used to write DOS applications. The high-level language syntax in C is simi- 
lar to that of many other high-level languages and even programmers unfa- 
miliar with C will understand the syntax. TIGA, however is not restricted to 
Microsoft C, although this initial release does rely on the Microsoft C calling 
conventions. Future versions of TIGA may be developed for other C compil- 
ers and other languages. 

The current version of TIGA also provides a simple interface for Microsoft 
assembly language programmers. The three TIGA include files (t iga . h, 
extend. h, and typedef s .h) all have assembly language equivalents that 
use macros to provide a simple interface to call TIGA functions. An example 
of how to call TIGA functions from the assembler is provided in the 
\tigapgms\asmtst directory. Consult the readme. 1st file in that directory 
for more details on the use of macros. Also provided in the include files are 
macros used to simplify the definition of user extensions. These macros, 
which mirror their C counterparts, are described in Chapter 4 of this user's 
guide. 
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The following sections list the TIGA primitives, first in their functional 
groups, and then alphabetically, with a description and example of their use. 
Appendix B provides further information concerning the drawing functions. 

This chapter describes the TIGA application interface, including the follow- 
ing topics: 

Section Page 

3.1 Base Set of TIGA Primitives 3-2 

3.2 Summary Table of Functions by Functional Group 3-3 

3.3 Alphabetical List of Functions 3-13 
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3.1 Base Set of TIGA Primitives 

From an application programmer's point of view, TIGA (Texas Instruments 
Graphics Architecture) consists of a set of functions which the application 
can invoke to perform graphics-related operations. These functions may run 
entirely on the host PC, on the TMS340 board, or on both. They fall into two 
classes, core and extended: 

Ql Core Primitives 

The core primitives, such as set_palet, are always available during a 
TIGA session. 

Q Extended Primitives 

The extended primitives, such as f III_rect, consist primarily of drawing 
functions. They are extended because the application has to load them 
when initializing TIGA. If the application requires installation of its own 
drawing functions, with parameters different from those used in TIGA, 
the extended primitives can be excluded at initialization time. Excluding 
the extended primitives frees up memory on the TMS340 board for user 
extensions. 
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3.2 Summary Table of Functions by Functional Group 

3.2.1 Graphics System Initialization Functions 

Function Description Type 

ccl_is_alive Return if TIGACD is running Core 

functionjmplemented Return if a function is implemented Core 

get_config Return board configuration Core 

get_modeinfo Return board configuration Core 

get_videomode Return current emulation mode Core 

gsp_execute Execute a COFF program Core 

install_primitives Install extended primitives Core 

instalLusererror Install user error handler Core 

loadcoff Load a COFF program Core 

set_config Set graphics configuration Core 

set_timeout Set timeout timing value Core 

set_videomode Set emulation mode Core 

synchronize Make host wait for GSP to idle Core 

The graphics system initialization functions deal with the initialization of the 
TIGA environment. Every application must call set_videomode with a tiga 
argument prior to invoking any other TIGA function. There are different 
styles of initialization that can be performed and they are detailed in the de- 
scription of set_videomode. Similarly, on exit, every TIGA function must 
call set_videomode with a mode of previous or some other IBM emulation 
mode. If the TMS340 board also serves as the primary graphics adapter, 
set_videomode switches the TMS340 board back into emulation mode 
prior to returning to DOS. 

To use the TIGA extended primitives, the application must first call the 
install_primitives function. This call needs to be done only once, if the dy- 
namic heap pool on the TMS340 board has not been reinitialized. 

The get_conf ig function returns the current board configuration (resolution, 
pixel size etc) to the application. Typically a board can be configured in more 
than one mode and the get_modeinfo, set_conf Ig functions are provided 
to inquire and select alternate modes. Typically an application uses whatev- 
er mode the board is set up in (via get_config). The end user can swap be- 
tween different modes with the TIGAMODE utility (described in Chapter 2). 
That utility makes calls to the get__modeinfo and set_config functions. 

TIGA consists of two distinct parts: a host part (the communication driver), 
which takes data from the application and sends it to one of the communica- 
tion buffers accessible to the TMS340, and a TMS340 part (the graphics 
manager), which takes the data from the host and performs the graphics op- 
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eration. The processors In these two portions work asynchronously. Some- 
times the host portion has to waitfortheTMS340portion;for example: when 
the TMS340 returns data to the host or when the host waits for a free com- 
munication buffer to use. The time the host has to wait for the TMS340 de- 
pends on what the TMS340 is doing for the application. 

TIGA has a built-in default time of 5 seconds, after which it displays an error 
message on the screen to inform the application that there was no communi- 
cation with the TMS340. This allows the user to break out if there is an error, 
or to continue waiting, if this default time is not acceptable it can be changed 
using the set_timeout function. The application can trap error calls by in- 
stalling its own error handler function using install_usererror . There is an 
example of this after the description of install_usererror. 

Sometimes it is desirable to force the host to wait for the TMS340 to com- 
plete an operation before proceeding. Consider the case where the 
TMS340 is performing a bitbit of data into memory and the host is then to 
upload the data using gsp2hostxy. Because the host and TMS340 work 
asynchronously, it is possible for the gsp2hostxy function to start copying 
data before the bitbit has completed. This can be solved by the application 
calling the synchronize function, which causes the host to wait until all 
TMS340 functions are completed, prior to the call to upload the data. 

3.2.2 Clear Functions 

Function Description Type 

clear_frame_buffer Clear entire frame buffer Core 

clearjDage Clear current drawing page Core 

clear_screen Clear screen Core 

The clear functions provide different ways to clear the screen. They all at- 
tempt to utilize any special memory functions (such as shift-register trans- 
fers) that the board or the memory chips themselves may have to perform 
the clear function as quickly as possible. The clear_frame_buffer clears 
the entire frame buffer, which may consist of multiple display pages and 
areas of offscreen (non-displayable) memory. 

The clear_screen function clears only the visible portion of the screen. For 
configurations that contain multiple display pages, only the current drawing 
page is cleared. The clear_page function is similar to the clear_screen 
function except that it does not ensure that data in offscreen memory is kept 
intact. This is because, depending on how the frame buffer is designed, it 
may be possible to clear a page using shift-register transfers; however, cer- 
tain offscreen memory areas may also be affected. Thus, to keep offscreen 
memory integrity, an application should use the clear__screen function. If 
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offscreen memory integrity is not a concern, the ciear_page function may 
be tiie fastest option on certain boards. 



3.2.3 Graphics Attribute Control Functions 
Function Description 



Type 



Compare point to window Core 

Return foreground/bacl<ground colors Core 

Return current environment structure Core 

Return color plane mask Core 

Return pixel processing operation Core 

Return transparency mode Core 

Return windowing mode Core 

Set background color Core 

Set clipping rectangle Core 
Set foreground and background colors Core 

Set drawing origin Ext 

Set foreground color Core 

Set current pattern description Ext 

Set current pensize Ext 

Set color plane mask Core 

Set pixel processing operation Core 

Set transparency mode Core 

Set windowing mode Core 

Disable pixel transparency Core 

Enable pixel transparency Core 

The graphics output functions use implied operations called the graphics at- 
tributes to perform the drawing operations described below. These attrib- 
utes are initialized and can be queried using the functions in this group. The 
graphics attributes consist of 

Foreground Color Primary drawing color of all primitives. The color val- 
ue is an index running from to two-to-the-pow- 
er-of-the-current-pixel-size. The value will typically 
be an index into the current palette (see next section). 

Background Color Secondary drawing color, used in patterns, text and 
bitbit functions. 



cpw 

get_colors 

get_env 

getjDmask 

getjDpop 

getjransp 

get_windowing 

set_bcolor 

set_clip_rect 

set_colors 

set_draw_origin 

setjcolor 

set_patn 

set_pensize 

setjamask 

set_ppop 

setjransp 

set_windowing 

transp_off 

transp_on 



Plane Mask 
Pixel Processing 
Transparency 



Enables the bits in a pixel to represent different 
planes. 

Determines the operation performed on source and 
destination pixels in any pixel operation. 

Determines whether a pixel write should be Inhibited 
if the pixel color is transparent. 
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Windowing 
Drawing Origin 
Fill Pattern 
Drawing Pen 



Allows regions of the screen to be clipped to ensure 
no drawing occurs outside the designated window. 

By default the drawing origin is the top-left hand cor- 
ner of the screen, but this can be moved anywhere. 

Used by all the patn drawing functions that fill a re- 
gion with a pattern instead of a solid color. 

Used by all the pen drawing functions to outline a re- 
gion with a pen of the specified width and height, rath- 
er than with a single- pixel wide line. 



For further details concerning the drawing functions, see Appendix B. 



3.2.4 Palette Functions 



Function 



Description 



Type 



get_nearest_color 

get_palet 

getjDalet_entry 

init_palet 

set_palet 

set_palet_entry 



Return nearest color in a palette 
Return an entire palette 
Return a palette entry 
Initialize default palette 
Set an entire palette 
Set a palette entry 



Core 
Core 
Core 
Core 
Core 
Core 



The palette functions are graphics attributes and deserve special attention 
because they may vary from board to board. Ideally, the application should 
be able to set the palette to any particular desired value, but if the palette 
is in ROM, this is not possible. Use functionjmplemented to determine 
If the palette entries can be set. If they cannot be set, use the get_near- 
est_color function to find the best entry to the desired color stored in ROM. 
Also, different palettes allow different bits-per-gun. Determine the bits-per- 
gun using the paiet_gun_depth field in the CONFIG structure or the 
get_palet function. The get_palet and get_palet_entry functions return 
the physical colors stored in the palette. Thus, if a palette entry is set with 
8 bits of red to hexadecimal FF on a particular board (such as the Tl SDB), 
where only 4 bits per gun are used, invoking get_palet_entry for that entry 
would return a red value of FO to indicate that the LS 4 bits were ignored. 
An example describing this is shown after the description of 
get_palet_entry. 

If possible, the palette is initialized to a default set of commonly-used colors 
(defined in the tiga . h insert file) by a call to init__palet. 
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3.2.5 Graphics Output Functions 



Function 



Lconvex 

Loval 

IjDiearc 

Lpolygon 

Lrect 
frame_oval 
frame_rect 
patnfilI_convex 
patnfill_oval 
patnfilljDiearc 
patnfill_polygon 
patnfill_rect 
patnframe_oval 
patnframe_rect 
patnpenjine 
patnpen_ovalarc 
patnpenjDiearc 
patnpenjDoint 
patnpenjDolyline 
penjine 
pen_ovaIarc 
penjDiearc 
penjDoint 
penjDolyline 
seedjill 
seecl_patnfill 
styledjine 



Description 



Type 



drawjine Draw line Ext 

draw_oval Draw ellipse outline Ext 

draw_ovalarc Draw ellipse arc Ext 

draw_piearc Draw ellipse pie slice Ext 

draw_point Draw single pixel Ext 

draw_polyline Draw list of lines Ext 

draw_rect Draw rectangle outline Ext 

Draw solid convex polygon Ext 

Draw solid ellipse Ext 

Draw solid ellipse pie slice Ext 

Draw solid polygon Ext 

Draw solid rectangle Ext 

Draw oval border Ext 

Draw rectangular border Ext 

Draw patterned convex polygon Ext 

Draw patterned ellipse Ext 

Draw patterned pie slice Ext 

Draw patterned polygon Ext 

Draw patterned rectangle Ext 

Draw patterned oval border Ext 

Draw patterned rectangular border Ext 

Draw line with pattern and pen Ext 

Draw oval arc with pattern and pen Ext 

Draw pie slice with pattern and pen Ext 

Draw pixel with pattern and pen Ext 

Draw lines with pattern and pen Ext 

Draw line with pen Ext 

Draw an oval arc with pen Ext 

Draw pie slice with pen Ext 

Draw point with pen Ext 

Draw lines with pen Ext 

Fill region with color Ext 

Fill region with pattern Ext 

Draw styled line Ext 

The graphics output functions are self-explanatory. Specific examples on 
how to use fill patterns are shown in patnfill_piearc and for drawing pens 
in patnpenjine. These examples also explain other patn and pen func- 
tions. Additional examples of drawing functions are given for drawjine, 
draw_oval, draw__ovalarc, draw_point, draw_poiyline, fill_polygon, 
and styledjine. 

For further details concerning the drawing functions, see Appendix B. 
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3.2.6 Poly Drawing Functions 



Function 


Description 


Type 


draw_polyline 


Draw polyline 


Ext 


fill convex 


Fill convex polygon 


Ext 


filLpolygon 


Fill polygon 


Ext 


patnfill_convex 


Pattern fill convex polygon 


Ext 


patnfilljDolygon 


Pattern fill polygon 


Ext 


patnpen_polyline 


Pattern pen polyline 


Ext 


pen_polyline 


Pen polyline 


Ext 



The TIGA communication driver functions pass the arguments of all the 
TIGA primitives into acommunlcationbufferfortheTIGA graphics manager 
to use. Nearly all TIGA primitives have fixed size arguments that fit easily 
into the communication buffer. This is not the case with the poly drawing 
functions, which have a point list parameter that can be of any length. It is 
easy for the function to overflow the buffer, destroying the TIGA environ- 
ment. The application can either check the size of the data that it is sending, 
against the communication buffer size in the CONFIG structure, or it can use 
alternate entry points (with an _a appended to the function name), that use 
a buffer, allocated from the dynamic heap pool, to store the data. However, 
these alternate entry points are slower. 



3.2.7 Workspace Functions 
Function 



Description 



Type 



filLpolygon Fill polygon Ext 

get_wksp Return offscreen workspace Core 

patnfill_polygon Pattern fill polygon Ext 

set_wksp Set a temporary workspace Core 

The polygon fill functions use an implied operand of a temporary workspace. 
This workspace is a 1 bit-per-pixel representation of the display screen and 
may be allocated from offscreen-memory in the TIGA port for the board be- 
ing used. This can be determined by the get_wl(sp function. If the area can- 
not be allocated from offscreen-memory, then It must be allocated from heap 
and assigned using the set_wlcsp function. An example showing how to do 
this follows the fiii_polygon description. 



3.2.8 Pixel Array Functions 



Function 


Description 


Type 


bitbit 


Bitbit source array to destination 


Ext 


setjdstbm 


Set destination bitmap 


Ext 


set srcbm 


Set source bitmap 


Ext 


swap_bm 


Swap source and destination bitmaps 


Ext 


zoom rect 


Zoom source rectangle 


Ext 
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The bitbit function transfers a rectangular array of pixels in TMS340 
memory. The function uses two implied operands (source bitmap and desti- 
nation bitmap) which are set, by default, to the screen. When they are set 
to a linear address, the bitbit function can then save data offscreen and re- 
store it again (see example following set_dstbm). The bitbit function can 
also be used to expand a linear bitmap which is at 1 bit-per-pixel to a color 
bitmap (see example following zoom_rect). 

The destination bitmap is an implied operand for all drawing functions. If it 
is set to anything other than the screen, all drawing primitives (other than 
bitbit) abort. In the future, linear drawing capability may be added to each 
of the drawing functions so they can draw into a linear bitmap. 

The source bitmap is ignored by all functions except bitbit and zoom_rect. 
The latter is used to scale a source pixel array intoany size destination array. 
See the example following the function description. 



3.2.9 Text Functions 



Function Description Type 

deletejont Remove a font from the font table Ext 

getjontinfo Return font physical information Core 

getjextattr Return text rendering attributes Ext 

init_text Initialize text drawing environment Core 

installjont Install font into font table Ext 

selectjont Select an installed font for use Ext 

setjextattr Set text rendering attributes Ext 

text_out Render an ASCII string Core 

text_width Return the width of an ASCII string Ext 



The text functions are partly core and partly extended primitives. In the core 
is a system font and the text_out primitive along with get.fontinfo (which 
returns font size information) and init_text (to reset the text environment). 
The extended primitives install_font, select_font, and delete_font allow 
the addition of TIGA fonts. There are over 1 00 TIGA fonts available, which 
the application loads from disk on the host side (or links-in with the host 
application) and downloads onto the TMS340 side. An example illustrating 
this is in install_font. The set/getjextattr function allows the text attrib- 
utes such as inter-character spacing, to be adjusted by the application. 

For more details on the font structure, see Appendix A. 
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3.2.10 Cursor Functions 

Function Description Type 

get_curs_state Return cursor current state Core 

get_curs_xy Return cursor position Core 

set_curs_shape Set cursor shape Core 

set_curs_state Make cursor visible/invisible Core 

set_curs_xy Set current cursor position Core 

The cursor functions support the graphics cursor routine. The cursor can be 
enabled or disabled via the set_curs_state function and its position can be 
modified using set_curs_xy. The set_curs_shape enables an arbitrary 
shaped cursor to be used. An example showing how the cursor may be driv- 
en by the host mouse follows the description of set_curs_shape. 

3.2.11 Grapiiics Utility Functions 



Function 


Description 


Type 


get_pixel 


Read contents of a pixel 


Ext 


Imo 


Return left-most-one bit number 


Core 


page_busy 


Return status of page flipping 


Core 


pagejiip 


Set display and drawing pages 


Core 


peek_breg 


Read from a B-file register 


Core 


poke_breg 


Write to a B-file register 


Core 


rmo 


Return right-most-one bit number 


Core 


wait_scan 


Wait for a designated scan-line 


Core 



The graphics utility functions are a group of miscellaneous graphics-related 
functions, most of which require no explanation other than what is given with 
the individual functions. 

The waitjscan and page_f lip/busy functions are mechanisms to aid ani- 
mated sequences. wait_scan waits for a particular scan line, enabling data 
to be drawn on one part of the screen while a different part is being dis- 
played. This feature provides a flicker-free display but is limited in the 
amount that It can draw before the display moves to the area that is being 
drawn into. The use of multiple drawing pages is a much more effective way 
where one page can be drawn while another is being displayed. This is the 
only way to ensure a flicker-free display. However, it does require at least 
double the amount of memory for the frame buffer. 

The CONFIG structure supplies the number of display pages. If the number 
of pages is greater than 1 , use the pagejiip function to select a page for 
drawing and a page for displaying. The flip of the pages is synchronized with 
the start of VBLNK for the best visual effect. The page_busy function must 
be polled prior to drawing into the new page. 

3-1 TIGA Application Interface 



sssmtmmisoinsmtii imumimmciM 



Summary Table of Functions by Functional Group 



3.2.12 Pointer-Based Memory Management Functions 

Function Description Type 

get_offscreen_memory Return offscreen memory blocks Core 

gsp2gsp Copy from GSP memory to GSP memory Core 

gsp_calloc Allocate and clear GSP memory Core 

gspjree Deallocate GSP memory Core 

gsp_malloc Allocate GSP memory Core 

gsp_maxheap Return largest free block Core 

gsp_minit Reinitialize GSP memory heap pool Core 

gsp_reaIloc Resize allocated block of memory Core 

The heap management functions (gsp_malloc, gsp_free, gsp_cailoc, 

gsp_realioc) are familiar to C application programmers. Identical heap 
management for host memory is provided in Microsoft C runtime support. 
The gsp_minit function initializes the heap pool (freeing all allocated point- 
ers). Because the program memory is shared between stack and heap, this 
function can also be used to adjust the memory used for stack (and thus, 
leaving the remainder memory for heap). The gsp_maxheap function re- 
turns the largest contiguous block of heap available (which is also the total 
heap size at the start of an application) and can determine how much data 
can be loaded from the host to the TMS340. 

The gsp2gsp function provides a memory copy function (as opposed to 
bitbit, which is a pixel array copy). It handles overlapping memory areas. 

The get_offscreen_memory function returns data concerning the size and 
addresses of available offscreen memory, which are separate from the heap 
pool. Allocation of these areas is performed by the application. The off- 
screen memory may be used for the temporary workspace (see Section 
3.2.7). 

3.2.13 Communication Functions 

Function Description Type 

cop2gsp Copy coprocessor to GSP memory Core 

fieid_extract Extract data from GSP memory Core 

fieldjnsert Insert data into GSP memory Core 

get_vector Get address at a TMS340 trap vector Core 

gsp2cop Copy GSP memory to coprocessor Core 

gsp2host Copy from GSP into host memory Core 

gsp2hostxy Copy rectangular area from GSP to host Core 

host2gsp Copy from host into GSP memory Core 

host2gspxy Copy rectangular area from host to GSP Core 

set_vector Set contents of GSP trap vector Core 
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The communication functions transfer data between iiost and TMS340 
memory spaces, or between Ti\/IS340 and its coprocessor. 



3.2.14 Extensibility Functions 
Function 



Description 



Type 



create_alm 

create_esym 

flusli_esym 

flusii_extended 

getJsrjDriorities 

lnstall_alm 

lnstall_primitives 

lnstall_rlm 

setjnterrupt 



Create absolute load module Core 

Create external symbol table file Core 

Flush external symbol table file Core 

Flush all user extensions Core 
Return interrupt service routine priorities Core 

Install absolute load module Core 

Install extended drawing primitives Core 

Install relocatable load module Core 

Set an interrupt handler Core 



The extensibility functions are all concerned with extensibility. Their use is 
described In detail in Chapter 4. 
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3.3 Alphabetical List of Functions 

This section contains a reference for TIGA functions in aipiiabetica! order. 
Eacli discussion 

□i Siiowstlie syntax of tlie function declaration and the arguments that the 
function uses. 

Q Contains a description of the function operation, which explains input 
arguments and return values. 

Qi Provides an example of the use of some functions. 
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bitbit BitBIt in GSP Memory 

SyntBX void bitbit (width, height, srcx, srcy, dstx, dsty) 

short width; 
short heights- 
short srcx; 
short srcy; 
short dstx; 
short dsty; 

Type Extended 

Description The bitbIt function copies data from the TMS340's source bitmap, which is 
installed by the set_srcbm function into the destination bitmap. The desti- 
nation bitmap is in turn installed by the set_dstbm function. The bitmap data 
is a rectangular area whose top left-hand corner is at coordinates 
(srcx, srcy) In the source bitmap of size width by height, into the destina- 
tion bitmap, starting at coordinates (dstx, dsty). The pixel size of the two 
bitmaps should either be equal or, if they are not, one of the pixels sizes must 
be equal to 1 . 

If the pixel sizes are equal, then the rectangular area is copied. If both source 
and destination bitmaps are set to the screen, then a check is made to see 
if the areas overlap. If they do, the bitbit direction is set to avoid destroying 
the source bitmap before it is copied. 

If the source bitmap pixel size is 1 , the bitmap is expanded to color in the 
destination array. 1s in the source bitmap are drawn in the current fore- 
ground color and Os are drawn in the current background color. 

If the destination bitmap pixel size is equal to 1 , then a contract function is 
performed. Pixels in the source array that are equal to the current back- 
ground color are set to in the destination array. All other colors are set to 
1. 

When the destination bitmap is set to the screen, the function attempts to 
clip the destination bitmap to the current clipping rectangle set by the 
set_clip_rect function. This only occurs if the pitch of the source and desti- 
nation pitch are a power of two (greater than or equal to 16). The source 
pitch is set by the user in the set_srcbm function. If the destination bitmap 
is the screen, its pitch is defined in the disp_pitch field of the CONFIG 
structure (see Appendix A). If the pitches are not a power of two, you must 
pre-clip the destination bitmap. 
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BitBIt in GSP Memory bitbit 

Example finclude <typedefs.h> 
#include <tiga.h> 
finclude <extend.h> 

CONFIG config; 

mainO 
{ 

if (set_videomode(TIGA, INIT | CLR_SCREEN) ) 

{ 

if (install_primitives >= 0) 

{ 

get_conf ig (& config) ; 

set_f color (BLUE) ; 

/* fill the top left quarter of the screen */ 

/* with a blue rectangle */ 

f ill_rect ( config . mode . disp_hres»l , 

config. mode. disp_vres»l, 0, 0); 
/* copy one quarter of the rectangle with top */ 
/* left-hand corner at the center of the screen */ 
bitbit (config. mode. disp_hres»2, 

config. mode. disp_vres»2, 0, 0, 

config. mode. disp_hres»l, 

config. mode. disp_vres»l) ; 

} 

set_videomode (PREVIOUS, INIT) ; 
} 
} 
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Cd_ls_allve Return if TIGACD is l=iunning 
Syntax int cd_is_alive() 

Type Core 

Description The cd_is_alive returns true (nonzero) if the communication driver (CD) 
has been installed, or false (zero), otherwise. This function is an alternate 
entry point to set_videomode for applications that require only the host- 
side entry points of TIGA without loading the graphics manager. If this 
function returns true (nonzero), then the following host-only primitives may 
be used: 



Oi 


field_extract 


Q 


fieldjnsert 


Q 


gsp2host 


^ 


gsp2hostxy 


Q 


gsp.execute 


Oi 


host2gsp 


Qi 


host2gspxy 


Oi 


loadcoff 



Before a call to any other TIGA function, a call must first be made to 
set.videomode with a tiga parameter. 
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Clear Entire Frame Buffer Clear Jrame^buffer 
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Syntax void clear_frame_buffer (color) 

long color; 

Type Core 

Description The clear_frame_buffer function performs a rapid clearing of tiie entire 
display memory, by setting it to the color index specified. If the color is set 
to -1 the current background color is used. If the configuration is such that 
the screen can be cleared using shift-register transfers, this is done, 
providing a very rapid clearing. If the configuration contains multiple display 
pages all pages are cleared. The integrity of offscreen data cannot be 
guaranteed using this function. If this is of concern to the calling program, 
then the clearjscreen function should be used. 

If the graphics display board uses display memory to store palette informa- 
tion (as in the TMS34070), this area should be left intact by this function. 
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Clear_page Clear Current Drawing Page 

Syntax void clear_page (color) 

long color; 

Type Core 

Description The clearj)age function performs a rapid clearing of tiie current drawing 
page by setting it to tlie color index specified. If the color is set to -1 the cur- 
rent background color is used, it provides very rapid clearing if the 
configuration allows the use of shift-register transfers. If the configuration 
contains multiple display pages, only the current drawing page is cleared. 
However, the integrity of offscreen data cannot be guaranteed using this 
function. If this is of concern to the calling program, then the clearjscreen 
function should be used. 

if the graphics display board uses display memory to store palette informa- 
tion (as in the TMS34070), this area should be left intact by this function. 
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Clear Screen Clear screen 



Syntax void clear_screen (color) 

long color; 

Type Core 

Description The clear_screen function performs a rapid clearing of only the visible 
portion of the display memory, by setting it to the color specified index. If the 
color is set to -1 , the current background color is used. It provides very rapid 
clearing if the configuration allows the use of shift-register transfers. 
However, this function clears only the current drawing page (in a multiple 
paged frame buffer) and does not affect any offscreen memory. If the 
offscreen memory data does not have to be conserved, then a more rapid 
fill may be possible using the clear_page function. 

If the graphics display board uses display memory to store palette informa- 
tion (as in the TMS34070), this area should be left intact by this function. 

Example See functionjmplemented. 
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C0p2gsp Copy from Coprocessor Memory to GSP Memory 

Syntax void cop2gsp(copid, copaddr, gspaddr, length) 

short copid; 
long copaddr; 
long gspaddr; 
long length; 

Type Core 

Description The cop2gsp function copies data from the address space of the coproces- 
sor with ID copid (a number from 0—7, with 4 being broadcast, as defined 
in the TMS34020 specification) into TMS340 memory. The data to be trans- 
ferred is in 32-bit long words. 
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Compare Point to Window cpw 

Syntax short cpw(x, y) 

short X, y; /* pixel coordinates */ 

Type Core 

Description The cpw function generates 4-bit outcode based on a pixel's position rela- 
tive to the current clipping window. Arguments x and y are the coordinates 
of the pixel. 

The outcode value is contained in the 4 LSBs of the return value. Outcode 
values include 

OOOO2 if the point lies within the window. 

01 XX2 if the point lies above the window. 

1 0XX2 if the point lies below the window. 

xx01 2 if the point lies left of the window. 

xx1 O2 if the point lies right of the window. 

Refer to the TMS34010 User's Guideior a detailed description of the out- 
codes. 
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Create_alm Create Absolute Load Module 

Syntax int create_alm(rlm_name, alm_name) 

char far *rlin_name; 
char far *alm_name; 

Type Core 

Description The create.alm function converts the relocatable load module (specified 
by rim_name) into an absolute load module and saves it under the filename 
specified by aim_name. If no file extension is supplied for the RLM, then an 
extension of . rlm is used. If no extension is supplied for the ALM, then an 
extension of . alm is used. If no path information is specified, this function 
looks first in the current directory and then in the directory specified by the 
TIGA environment variable. 

if the ALM file already exists, the procedure does nothing. This saves time 
by creating the ALM file only once. If a new ALM file is desired, the old one 
must be deleted explicitly. For more details on extensibility and an example 
of the use of this function refer to Chapter 4. 

If the function terminates correctly, zero is returned; if an error occurs, a neg- 
ative error code is returned.This function returns these error codes: 

Error Description 

Code 

-1 System Error - Could not find tigalnk in the main tiga directory, 
either the tiga environment variable -m option is not set or that 
directory does not contain tigalnk . exe. 

-3 Out of Memory - Not enough host memory to run tigalnk or not 
enough TMS340 memory to store the ALM 

-4 Communication Driver not Running - Run tigacd 

-5 Graphics l\/lanager not Running - Run tigalnk -ix 

-6 Missing RLM - Either the spelling of the RLM filename does not 
match the RLM filename in the current directory or the -i option of 
the TIGA environment variable is not set up. 

-7 Symbol File Error -I/O error obtained in accessing the symbol file. 
The -m option of the TIGA environment variable is not set or the 
directory does not contain tiga340 . sYMorthefile is corrupt. In the 
latter case recopy this file from your backup disk. 

-1 Symbol Reference- An unresolved symbol was referenced by the 
RLM. Determine the name either by producing a link map for the 
RLM or by invoking tigalnk from the command line using the -ec 
flag. 
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Create Absolute Load Module create aim 



Error Description (continued) 

Code 

-12 Symbol Table Mismatch - The modules installed in the symbol 
table do not match those the TIGA graphics manager has installed. 
Reinitialize the modules by a call to flush_extended and install 
them again. 
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Create_esym Create External Symbol Table File 



Syntax 



Type 



int create esym(gm name) 



char far *gin_name; 



Core 



Description The create_esym function does not need to be called by the user. It is pro- 
vided as a procedural level interface to the linking loader. It should be used 
instead of calling the linking loader directly, to provide compatibility with fu- 
ture versions of TIGA. 

This function creates an external symbol table file from the supplied TIGA 
graphics manager file. If no file extension is supplied, then a file extension 
of .OUT is used. The external symbol table is saved under the name 
TiGA340.SYM.Aftercreation, this file willcontain only theglobal(orexternal) 
symbols that were contained in the graphics manager file. During subse- 
quent installation of relocatable load modules, this file is used to resolve ex- 
ternal references. Also any external symbols contained in a RLM are added 
to this file during the installation process so those symbols can be refer- 
enced by other RLMs. 

If no pathname information is supplied for the gm_name, this function uses 
the path specified by the TIGA environment variable. The external symbol 
file created also uses this path information. For more details on extensibility, 
the use of this function refer to Chapter 4. 

If an error occurs, a negative error code is returned. If this function termi- 
nates normally, zero Is returned. 

This function returns these 



Error 
Code 

-1 



Description 

System Error -Could not find tigalnk in the main tiga directory, 
either the tiga environment variable -m option is not set or that di- 
rectory does not contain tigalnk.exe. 



-4 Communications Driver not Running - Run tigacd. 

-5 Graphics R/lanager not Running - Run tigalnk -ix. 

-7 Symbol File Error - I/O error obtained in accessing symbol file. 
The -m option of the TIGA environment variable is not set or the di- 
rectory does not contain tiga340 . sym or the file is corrupt. In the 
latter case recopy this file from your backup disk. 

-1 1 COFF File not Absolute ~ The coff file argument for this function 
is not linked to an absolute address. 
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Error Description (continued) 

Code 

-12 Symbol Table Mismatch - The modules Installed In the symbol 
table do not match those the TIGA graphics manager has installed. 
Reinitialize the modules by a call to flush_extended and install 
them again. 
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delete font Delete a Font from Table 



Syntax int delete_font(id) 

short id; 

Type Extended 

Description The delete_font function removes from the font table the installed font ref- 
erenced by id. A nonzero value is returned if the font was successfully 
removed, and a value of zero if the font was not installed. Note that if the 
font removed was also the one selected for current text drawing operations, 
the system OEM font is selected. 
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Syntax void draw_line(xl, yl, x2, y2) 

short xl, yl; /* start coordinates 

short x2, y2; /* end coordinates 

Type Extended 






Description The drawjine function uses Bresenham's algorithm to draw a line from the 
starting point to the ending point, xi and yl specifythe starting coordinates; 
x2 and y2 specify the ending coordinates. The line is one pixel thick and is 
drawn in the current foreground color. 
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Example #include <typedefs.h> 
finclude <tiga.h> 
#include <extend.h> 

CONFIG config; 

main ( ) 
{ 

short xs, ys, xe, ye, i, color; 

if (set_videomode(TIGA, INIT | CLR_SCREEN) ) 
{ 

if (install_primitives >= 0) 
{ 

get_config(&config) ; 
xs = config. mode. disp_hres»l; 
ys == config. mode. disp_vres»l; 
set_fcolor(RED) ; 

/* set up an add pixel processing option to affect */ 
/* overlapping lines in the center of the screen */ 
set_ppop{16) ; 

/* draw lines at diff . orientations */ 

for (xe =5/ ye = 5; xe <= config. mode. disp_hres- 6; 
xe += 17) 

draw_line(xs, ys, xe, ye); 
for (xe =5, ye = config. mode. disp_vres-6; 

xe <= config. mode. disp_hres-6; xe += 17) 
draw_line(xs, ys, xe, ye); 
for (xe = 5, ye = 10; ye <= config. mode. disp_vres-6; 
ye += 17) 

draw_line(xs, ys, xe, ye); 
for (xe = config. mode. disp_hres-6, ye = 10; 

ye <= config. mode. disp_vres- 6; ye +== 17) 
draw_line(xs, ys, xe, ye); 
} 

set_videomode (PREVIOUS, INIT) ; 
} 
} 
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Syntax void draw_oval(w, h, xleft, ytop) 

short w, h; /* width, height of rect. */ 
short xleft, ytop; /* coordinates at top left corner */ 

Type Extended 

Description The draw_oval function draws the outline of an ellipse, given the minimum 
enclosing rectangle in which the ellipse is inscribed. The ellipse is in stan- 
dard position, with its major and minor axes parallel to the coordinate axes. 
The enclosing rectangle is defined by four arguments: 

13 The width w 

Q The height h 

Qi The coordinates of the top left corner (xief t , ytop) 

The outline is one pixel thick and is drawn in the current foreground color. 
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Example finclude <typedefs.h> 
#include <tiga.h> 
#include <extend.h> 

CONFIG config; 



main ( ) 
{ 

int w, h, X, y; 

if (set_videomode(TIGA, INIT | CLR_S GREEN ) ) 

{ 

if (install_primitives () >= 0) 
{ 

get_config(&config) ; 

/* restrict drawing to window in center of screen */ 
set_clip_rect (config. mode. disp_hres»l, 
config . mode . disp_vres»l , 
config . mode . disp_hres»2 , 
config.mode.disp_vres»2) ; 
set_f color (GREEN) ; 

/* draw various sizes ellipses */ 

for (w = 0, X = 4; w < config. mode. disp_hres/20; 
++W, X += w + 3) 
for (h = 0, Y = 4; h < config. mode. disp_vres/20; 
++h, y += h + 3) 
draw_oval (w, h, x, y) ; 
} 

set_videomode (PREVIOUS, INIT) ; 
} 
} 



3-30 TIGA Application Interface 



Draw Oval Arc draw ovalarc 



Syntax void draw_ovalarc (w, h, xleft, ytop, theta, arc) 

short w, h; /* width and height */ 

short xleft, ytop; /* top left corner */ 

short theta; /* starting angle (degrees) */ 

short arc; /* angle extent (degrees) */ 

Type Extended 

Description The clraw_ovaIarc function draws an arc taken from an ellipse. The ellipse 
is in standard position, with the major and minor axes parallel to the coordi- 
nate axes. The arc is one pixel thick and is drawn in the current foreground 
color. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

Q The width w 

Qi The height h 

Q The coordinates of the top left corner (xleft, ytop) 

The last two arguments define the limits of the arc: 

Qi The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun- 
terclockwise. 

Qi The arc extent, arc, specifies the number of degrees (positive or nega- 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,4-359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 
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Example #include <typedefs.h> 
#include <tiga.h> 
finclude <extend.h> 

CONFIG config; 



/* X coordinate of screen center */ 
#define XC (config. mode. disp_hres»l) 
/* y coordinate of screen center */ 
#define YC (config. mode. disp_vres»l) 
/* X coordinate of screen limit */ 
#define XMAX (config. mode. disp_hre'te-4) 
/* y coordinate of screen limit */ 
#define YMAX (config. mode. disp_vres-4) 
/* X increment */ 

#define DX (config. mode. disp_hres/40) 
/* y increment */ 

#define DY (config. mode. disp_vres/40) 
#define MAXBYTES 2048 

main ( ) 
{ 

short w, h; 

PTR addr; 

if (set_videomode(TIGA, INIT | CLR_S GREEN ) ) 

{ 

if (install_primitives >= 0) 

{ 

get_config(&config) ; 

/* draw a spiral */ 

set_f color (YELLOW) ; 

for (w = XMAX, h = YMAX; w > DX; h -= DY) 

{ 

draw_ovalarc (w, h, XC-w/2, YC-h/2, 0, 270); 

w -= DX; 

draw_ovalarc (w, h, XC-w/2, YC-h/2, 270, 90); 

} 

addr = gsp_malloc (MAXBYTES) ; 
set_f color (GREEN) ; 
seed_f ill (XC, YC, addr, MAXBYTES) ; 
gsp_f ree (addr) ; 
} 

set_videomode (PREVIOUS, INIT) ; 
} 
} 
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Draw Pie Arc draw_piearc 



Syntax 



void draw_piearc (w, h, xleft, ytop, theta, arc) 



short w, h; 
short xleft/ ytop; 
short theta; 
short arc; 



/* width and height 

/* top left corner 

/* starting angle (degrees) 

/* angle extend (degrees) 



*/ 
*/ 
*/ 
*/ 



Type 



Extended 



Description The draw_piearc function draws an arc taken from an ellipse. Two straight 
lines connect the two end points of the arc with the center of the ellipse. The 
ellipse is in the standard position, with the major and minor axes parallel to 
the coordinate axes. The arc and the two lines are all one pixel thick and are 
drawn in the current foreground color. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

Q The width w 

Q[ The height h 

□i The coordinates of the top left corner (xieft, ytop) 

The last two arguments define the limits of the arc: 

Qi The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle, and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun- 
terclockwise. 

Qi The arc extent, arc, specifies the number of degrees (positive or nega- 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 

Example See patnfill_piearc 
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draw_point Draw Point 

Syntax void draw_point (x,y) 

short X, y; /* pixel coordinates */ 

Type Extended 

Description The draw_point function draws a single pixel. Arguments x and y give the 
XY coordinates of the designated pixel. The pixel is drawn in the current 
foreground color. 

Example #include <typedefs.h> 
#include <tiga.h> 
#include <extend.h> 

CONFIG config; 

main ( ) 
{ 

int i, X, y, xy, yx; 

if (set_videomode(TIGA, INIT | CLR_SCREEN) ) 
{ 

if (install_pri]:nitives () >= 0) 
{ 

get_config(&config) ; 

set_f color (CYAN); 

x = xy = 0; 

y = yx = config. mode. disp_vres»l; 

/* draw Lissajous pattern in dots */ 

for (i = 1200; i > 0; — i) 

{ 

draw_point (x+ (config. mode. disp_hres»l) , 

y+ (config. mode. disp_vres»l) ) ; 
X += yx » 4; 
yx -= X » 4; 
y += xy » 5; 
xy -= y » 5; 
} 
} 

set_videomode (PREVIOUS, INIT) ; 
} 
} 
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Draw Polyline draw_polyline 



Syntax typedef struct 

{ 

short x; 
short y; 
} POINTS; 

void draw_polyline (n, points) ; 
short n; 
POINTS far *points; 

Type Extended 

Description The draw_polyline function draws n single pixel-wide lines whose end- 
points are supplied In an array of structures, described in the syntax. 
Note that for the polygon drawn to be closed, the calling program must en- 
sure that the first and last points are the same. 

The function requires two input arguments: 

Q[ The first argument, n, defines the number of vertices in the polygon. 

□i The second argument, points, is an array in which each pair of adja- 
cent 1 6-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

The argument points can be of any length. The application can easily 
overflow the command buffer used by the host processor to send the 
function parameters to the TMS340. The size of the command buffer is in 
the CONFIG structure (described in Appendix A) returned by the get_con- 
f ig function. The application must check that the data sent will not overflow 
this buffer. 

The number of points that can be sent is given by the following formula: 

com_buffer_size (in bytes) - 10 



n< 



An alternate entry point draw_polylme_a with the same parameterization 
is supplied to check the size of the data to be sent. If the command buffer 
overflows, draw_polyline_a attempts to allocate a temporary buffer in 
heap. In this way, the application is freed from having to check the size of 
the data being transferred; however, the invocation of the function takes 
longer, because the length of the data must be parsed. If there Is not enough 
room to store the temporary buffer in TMS340 memory, the error function 
is invoked (which can be trapped by the lnstall_usererror function). 
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Example #include <typedefs.h> 
#include <tiga.h> 
#include <extend.h> 

CONFIG config; 



/* screen independent coordinates of a cube */ 

short far cube [ ] = 

{ 

-2,+l, -2,-2, -1,-1, -1/+2, -2,+l, 

-2,-2, +1,-2, +2,-1, -1,-1, -2,-2, 

-1,-1, +2,-1, +2, +2, -l,+2, -1,-1, 

}; 

mainO 
{ 

int dx, dy, i; 

if (set_videomode(TIGA, INIT | CLR_SCREEN) ) 

{ 

if (install_j>riinitives >= 0) 

{ 

get_config(& config) ; 

set_f color (MAGENTA) ; 

dx = config. mode. disp_hres»4; 

dy = config. mode. disp_vres»4; 

/* scale cube coordinates to fit the resolution */ 

for (i =0; i < sizeof (cube) /sizeof (short) ; ) 

{ 

cube[i++] *= dx; 

cube[i++] *= dy; 

} 

/* move draw origin to the center of the screen */ 

set_draw_origin (config. mode. disp_hres»l, 
config. mode. disp_vres»l) ; 

/* draw the outline of the cube */ 

draw_polyline ( (sizeof (cube) /sizeof (short) ) »1/ cube) ; 
} 
set_videomode (PREVIOUS, INIT) ; 

} 
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Draw Rectangle draw_rect 

Syntax void draw_rect(w, h, xleft, ytop) 

short w, h; /* width and height of rectangle */ 
short xleft, ytop; /* coordinates at top left corner */ 

Type Extended 

Description The draw_rect function draws the outline of a rectangle. The first four argu- 
ments define the rectangle: 

Qi The width w 

^k The height h 

□i The coordinates of the top left corner (xief t , ytop) 

The outline is one pixel wide and is drawn in the current foreground color. 

The draw_rect function is equivalent to the following four calls to the 
drawjine function: 

draw_line(xleft, ytop, xleft+w, ytop) ; 
draw_line(xleft, ytop+h, xleft+w, ytop+h) ; 
draw_line(xleft, ytop+1, xleft, ytop+h-2) ; 
draw_line(xleft+W/ ytop+1/ xleft+w, ytop+h-2); 



3-37 



f ield_extract Extract Data from GSP Memory 

Syntax unsigned long field_extract (gptr, fs) 

unsigned long gptr; /* pointer to GSP memory address */ 
unsigned short fs; /* field size */ 

Type Core 

Description The f ield_extract function returns the 32-bit, zero-extended data from the 
TMS340 memory address specified by gptr. The field size parameter f s 
must be between 1 and 32 inclusive and specifies the number of bits to read 
from TMS340 memory. There are no restrictions on the alignment of the 
TMS340 address. 
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Syntax void f ield_insert (gptr, f s, data) 

unsigned long gptr; /* pointer to GSP memory address */ 
unsigned short fs; /* field size */ 

unsigned long data; /* data to be inserted */ 

Type Core 

Description The f ieldjnsert function writes the value of data into the TMS340 memory 
specified by gptr. The field size parameter f s must be between 1 and 32 
inclusive and specifies the number of bits to be written. Bit (the least 
significant bit) of data is written first, followed by bit 1 and so on until the 
specified number of bits have been written. There are no restrictions as to 
the alignment of the TMS340 address. 
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fill_COnvex FHI Convex Polygon 

Syntax typedef struct 

{ 

short x; 

short y; 
} POINTS; 

void f ill_convex (n, points); 
short n; 
POINTS far *points; 

Type Extended 

Description The f lll_convex function fills a convex polygon, given a list of points repre- 
senting the vertices. To be drawn correctly, the polygon must have at least 
three vertices visible. The first and last points must be the same to ensure 
that the polygon is closed. The polygon is solid-filled with the current fore- 
ground color. 

The function requires two Input arguments: 

Q The first argument, n, defines the number of vertices In the polygon. 

□i The second argument, points, Is an array In which each pair of adja- 
cent 1 6-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

f ill_convex is similar to the f ill_polygon function, but is specialized for rap- 
id drawing of convex polygons. It also executes more rapidly and supports 
realtime applications, such as animation. 

The filLconvex function automatically culls back faces to support 3-D 
applications. A polygon is drawn only if its front side is visible, that is, if it is 
facing toward the screen. If the vertices are specified in counterclockwise 
order, the polygon is assumed to be facing away from the screen and is 
therefore not drawn. 

The back face test is done by first comparing vertices n -2, n -1 , and to 
determine whether the polygon vertices are specified in clockwise (front 
face) or counterclockwise (back face) order. This test assumes the polygon 
contains no concavities. If the three vertices are colinear, the back face test 
is made again using the next three vertices, n-1 , 0, and 1 . The test repeats 
until three vertices are not colinear. If all the vertices are colinear, the poly- 
gon is invisible. 

One of the parameters of filLconvex Is a list of points that can be of any 
length. The application can easily overflow the command buffer used by the 
A host processor to send the function parameters to the TMS340. The size of 

the command buffer is in the CONFIG structure (described in Appendix A) 
returned by the get_conflg function. The application must check that the 
data sent will not overflow this buffer. 
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The number of points that can be sent is given by the following formula: 
com_buffer_size (in bytes) - 10 



n< 



An alternate entry point f ill_convex_a, with the same parameterization, is 
supplied to check the size of the data to be sent. If the command buffer 
overflows, fill_convex_a attempts to allocate a temporary buffer in heap. 
In this way, the application is freed from having to check the size of the data 
being transferred; the invocation of the function takes longer, because the 
length of the data must be parsed. If there is not enough room to store the 
temporary buffer in TMS340 memory, the error function is invoked (which 
can be trapped by the install_usererror function). 
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flll_OVai Fill Oval 

Syntax void fill_oval(w, h, xleft, ytop) 

short w, h; /* width, height of rect. */ 
short xleft, ytop; /* coordinates of top left corner */ 

Type Extended 

Description The fill_oval function draws an ellipse solid-filled with the current fore- 
ground color. The ellipse is in standard position, with its major and minor 
axes parallel to the coordinate axes. 

The ellipse is defined by the minimum enclosing rectangle in which it is in- 
scribed. The first four arguments define the rectangle: 

1^ The width w 

Q The height h 

Qi The coordinates of the top left corner (xieft, ytop) 

Example See draw oval 
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Syntax void f ill_piearc (w, h, xleft, ytop, theta, arc) 

short w, h; /* width and height */ 

short xleft, ytop; /* top left corner */ 

short theta; /* starting angle (degrees) */ 

short arc; /* extent of angle (degrees) */ 

Type Extended 

Description The f lll_piearc function draws a pie-shaped wedge solid-filled with the cur- 
rent foreground color. The wedge is bounded by an arc and two straight 
edges. The arc is taken from an ellipse in standard position, with its major 
and minor axes parallel to the coordinate axes. The two straight edges are 
defined by lines connecting the end points of the arc with the center of the 
ellipse. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

I^ The width w 

□i The height h 

Q The coordinates of the top left corner (xieft, ytop) 

The last two arguments define the limits of the arc: 

□i The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun- 
terclockwise. 

Qi The arc extent, arc, specifies the number of degrees (positive or nega- 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 

Example See patnfillj3!earc 
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Syntax typedef struct 

{ 

short x; 
short y; 
} POINTS; 

void f ill_polygon (n, points); 
short n; 
POINTS far *points; 

Type Extended 

Description The fill_polygon function fills a polygon, given a list of endpoints of the 
polygon. No restrictions are placed on the shape of the polygons filled by 
this function: edges can cross each other, filled areas can contain holes, and 
two or more filled regions can be disconnected from each other. The poly- 
gon is solid-filled with the current foreground color. Note that the first and 
last points of the array should be the same to close the polygon. 

The function requires two input arguments: 

^ The first argument, n, defines the number of vertices in the polygon. 

Qi The second argument, points. Is an array in which each pair of adja- 
cent 1 6-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

This function also takes as an implied argument a 1-bit representation of 
the frame buffer, which it uses as a temporary workspace. This workspace 
must be set up prior to invoking this function (via a call to the set_wksp func- 
tion). 

The argument points can be of any length. The application can easily 
overflow the command buffer used by the host processor to send the 
function parameters to the TMS340. The size of the command buffer is in 
the CONFIG structure (described in Appendix A) returned by the get_con- 
f ig function. The application must check that the data sent will not overflow 
this buffer. 

The number of points that can be sent is given by the following formula: 

com_buffer_size (in bytes) - 1 



n< 



An alternate entry point fill_poIygon_a, with the same parameterization, 
is supplied to check the size of the data to be sent. If the command buffer 
overflows fill_polygon_a attempts to allocate a temporary buffer in heap. 
In this way, the application is freed from having to check the size of the data 
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being transferred; however, the invocation of the function takes longer 
because the length of the data has to be parsed. If there is not enough room 
to store the temporary buffer in TMS340 memory, the error function is 
invoked (which can be trapped by the install_usererror function). 
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fiilj30lygon FHI Polygon 

Example #include <typedefs.h> 
#include <tiga.h> 
tinclude <extend.h> 

CONFIG config; 



/* screen independent coordinates of a cube */ 

short far cubel[] = {-2,+l, -2,-2, -1,-1, -l,+2, -2, +1}; 

short far cube2[] = {-2,-2, +1,-2, +2,-1, -1,-1, -2,-2,}; 

short far cube3[] = {-1,-1, +2,-1, +2, +2, -l,+2, -1,-1,}; 

main ( ) 
{ 

PTR wksp, pitch; 

int dx, dy, i; 

if (set_videomode(TIGA, INIT | CLR_SCREEN) ) 
{ 

if (installjprimitives () >= 0) 
{ 

/* see if wksp allocated */ 

get_config(&config) ; 

if ( !get_wksp(&wksp, &pitch) ) 

{ 

/* workspace not set up in offscreen memory, */ 
/*use malloc to create it */ 

pitch = l«lmo (config. mode. disp_hres) ; 
if (pitch < config. mode. disp_hres) pitch «= 1; 
wksp = gsp_malloc (( (pitch * config. mode. disp_vres) 

+ 7) / 8); 
set_wksp (wksp, pitch) ; 
} 

dx = config. mode. disp_hres»4; 
dy = config. mode. disp_vres»4; 

/* scale cube coordinates to fit the resolution */ 
for (i = 0; i < si2eof(cubel) /sizeof (short) ; ) 

{ 

cubel[i++] *= dx; 

cubel[i — ] *= dy; 

cube2[i++] *= dx; 

cube2 [i — ] *= dy; 

cubes [i++] *= dx; 

cubes [i++] *= dy; 
} 
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/* move draw origin to the centre of the screen */ 
set_draw_origin (conf ig.mode .disp_hres»l, 
config.mode.disp_vres»l) ; 
/* fill in the sides of the cube */ 

set_f color (BLUE) ; 
f ill_j)olygon ( (sizeof (cubel) /sizeof (short) ) »1/ 

cubel) ; 
set_f color (LIGHT_BLUE) ; 
f ill_polygon ( (sizeof (cube2) /sizeof (short) ) »1, 

cube2 ) ; 
set_f color (CYAN) ; 
f ill_polygon ( (sizeof (cubeS) /sizeof (short) ) »1, 

cubes ) ; 
} 
set videomode (PREVIOUS, INIT) ; 
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f II Lrect Fill Rectangle 

Syntax void fill_rect(w, h, xleft, ytop) 

short w, h; /* width and height of rectangle */ 
short xleft, ytop /* XY coords at top left corner */ 

Type Extended 

Description The fill_rect function draws a rectangle solid-filled with the current fore- 
ground color. The first four arguments define the rectangle: 

Q The width w 

Q The height h 

Q The coordinates of the top left corner (xief t , ytop) 

Exampie See bitbit 



3-48 TIGA Application Interface 



Flush External Symbol Table File f lush_esym 
Syntax int flush_esym() 

Type Core 

Description The flush_esym function does not need to be called by the application. It 
is a procedural level interface to the linking loader. It should be used instead 
of calling the linking loader directly to provide compatibility with future ver- 
sions of TIGA. 

This function flushes the external symbols from the symbol table 
TIGA340 . SYM, leaving just the global symbols in this file. 

For more details on extensibility and the use of this function, referto Chapter 
4. 

If the function terminates correctly zero is returned; if an error occurs, a neg- 
ative error code is returned.This function returns these error codes: 

Error Description 

Code 

-1 System Error- Could not find tigalnk in the main TIGA directory, 
either the TIGA environment variable -m option is not set or that 
directory does not contain tigalnk.exe. 

-4 Communications Driver not Running - Run tigacd 

-5 Graphics Manager not Running - Run tigalnk -ix 

-7 Symbol File Error - I/O error obtained in accessing symbol file. 
The -m option of the TIGA environment variable is not set or the 
directory does not contain tiga340 . sym or the file is corrupt. In the 
latter case, recopy this file from your backup disk. 
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f IUSh_extencled Flush ah User Extensions 
Syntax void f lush_extended ( ) 

Type Core 

Description The f iush_extended function performs two operations: first, it flushes the 
TIGA extended primitives and the installed user functions (both direct mode 
and C-packet) on the TMS340 side. Second, it removes the symbol table 
information stored on the host side. You can then install a new set of user 
functions. 

For more details on extensibility and the use of this function, refer to Chapter 
4. 
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Fill Frame Oval frame oval 

i55SS5S5BSSSSSSS5»S« 

Syntax void f rame_oval (w, h, xleft, ytop, dx, dy) 

short w, h; /* width, height of rect. */ 

short xleft, ytop; /* coordinates at top left corner */ 

short dx, dy; /* width, height of frame border */ 

Type Extended 

Description The f rame_oval function solid-fills an ellipse-shaped frame with the current 
foreground color. The frame consists of a filled region between two concen- 
tric ellipses. The portion of the screen enclosed by the frame Is not altered. 

The outer ellipse is specified in terms of the minimum enclosing rectangle 
in which it Is circumscribed. The first four arguments define the rectangle: 

Q[ The width w 

[^ The height h 

Q The coordinates of the top left corner (xief t , ytop) 

The thickness of the frame in the X and Y dimensions is defined by two addi- 
tional arguments: 

Qi dx specifies the horizontal distance between the outer and Inner el- 
lipses. 

^ dy specifies the vertical distance between the outer and inner ellipses. 

Example See patnfili_piearc. 
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f rame_rect FHI Frame Rectangle 

Syntax void f rame_rect (w, h, xleft, ytop, dx, dy) 

short w, h; /* width, height of enclosing rect. */ 
short xleft, ytop; /* coordinates at top left corner */ 
short dx, dy /* width, height of frame border */ 

Type Extended 

Description The f rame_rect function solid fills a rectangular shaped frame with the cur- 
rent foreground color. The frame consists of a filled region between two con- 
centric rectangles. The portion of the screen enclosed by the frame is not 
altered. 

The outer rectangle is specified in terms of the minimum enclosing rectangle 
in which it is inscribed. The first four arguments define the rectangle: 

Qi The width w 

Qi The height h 

□i The coordinates of the top left corner (xief t, ytop) 

The thickness of the frame in the X and Y dimensions is defined by two addi- 
tional arguments: 

Qi dx specifies the horizontal distance between the outer and inner rect- 
angles. 

□i dy specifies the vertical distance between the outer and inner rectan- 
gles. 
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Return if a Given Function is Implemented function_implemented 



«9maaSK!!5SWS5!y««SSKSSS«^^ 



Syntax int function_implemented(function_code) 

short function_code; 

Type Core 

Description Thefunctionjmplementedfunctionquerieswhetherafunction is implem- 
ented or not. Functions in TIGA have an associated f unction_code; some 
may not be implemented on every board, . 

The following functions are not likely to be implemented on all boards and 
should be queried with functionjmplemented before being invoked: 

cop2gsp 

set_j)alet 

get_palet 

set_palet_entry 

get_palet_entry 

set_transp 

gsp2cop 

init_palet 

The function codes themselves are contained in the main TIGA insert file, 
which contains the type and function declarations. The function codes are 
#defined to be the same as the function name but in upper case. Thus, the 
syntax to inquire if set_palet is implemented is 

if (function_implemented (SET_PALET) ) 
{ 
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f unction_implementecl Return if a Given Function is Implemented 

Example #include <typedefs.h> 
#include <tiga.h> 
#include <extend.h> 

CONFIG config; 

main ( ) 
{ 

short green_index; 

if (set_videomode(TIGA, INIT | CLR_SCREEN) ) 

{ 

/* if it is possible to set the palet entry value, */ 
/* set it to bright green */ 

if ( f unction_implemented ( SET_PALET_ENTRY) ) 
{ 

green_index =1; 

set_palet_entrY(green_index, 0, OxFF, 0, 0); 
} 

else 
{ 

/* if it is not possible to set the palet entry, */ 
/* (as in the case of a ROM-based palette) */ 
/* then get the index of the brightest green */ 
green_index = get_nearest_color (0, OxFF/ 0, 0); 
} 

/* use index to clear the screen to */ 

clear_screen (green_index) ; 
set videomode (PREVIOUS, INIT) ; 



} 



} 
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Return Foreground and Background Colors get_COlors 

Syntax void get_colors(f color, bcolor) 

short far *fcolor; 
short far *bcolor; 

Type Core 

Description The get_colors function returns both the foreground and background col- 
ors. 
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get_COnf ig Return Board Configuration 

Syntax 

I* V 

/* MODEINFO structure definition with the current mode of operation */ 

/* *l 

typedef struct 
{ 

long disp_j)itch; 

short disp_vres; 

short disp_hres 

short screen_wide 

short screen_high; 

short disp_psize; 

long pixel_mask; 

short palet_gun_depth; 

long palet_size; 

short palet_inset; 

short num_pages; 

short nuin_offscrn_areas; 

long wksp_addr; 

long wk.sp_pitch; 
} MODE INFO; 

I* V 

I* CONFIG structure definition of the current hardware configuration */ 
I* *i 

typedef struct 
{ 

short version_number; 

long coinm_buff_size; 

long sys_flags; 

long device_rev; 

short nuin_modes; 

short current_mode; 

long program_mem_start; 

long prograitijmem_end; 

long display_mem_start; 

long display_mem_end; 

long stack_si2e; 

long shared_mem_size; 

char far *shared_host_addr; 

PTR shared_gsp_addr; 

MODEINFO mode; 
} CONFIG; 

void get_config(config) 
CONFIG far *config; 
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Return Board Configuration get_COnf ig 



Type 



Core 



Description The get_config function returns a structure containing all board- and 
mode-specific information. Note that it Is very likely that the structure de- 
scribed above will change in subsequent revisions. Therefore, it is recom- 
mended that the elements of the structure be referenced symbolically by 
their field name, rather than as an offset to the start of the structure. Insert 
files are available to do this. 



The fields are as follows 

version number 



comm buff size 



sys flags 



device rev 



TIGA revision number, assigned by Texas Instru- 
ments. 

Size, in bytes, of the communications buffer; applica- 
tion needs to ensure that the data sent does not 
overflow this buffer, for commands which do not 
check the size of the downloaded data. 

Bits — 7 indicate Floating Point Units (FPUs) are 
present, in order to be compatible with the 
TMS34020 Coprocessor ID codes. Bits8— 1 5 are re- 
served. 



num modes 



current mode 



This function invokes the TMS340's REV instruction 
and return its result here. 

Number of extended modes for boards that allow the 
switching between different display setups. 

Mode number corresponding to the current operating 
mode. 

program_mem_start Start address of program memory. 

program_mem_end End address of program memory. 

dispiay_mem_start Start add ress of display memory. 

dispiay_mem_end End address of display memory. 

Default stack size can be modified using gsp_minit. 

Size (in bytes) of shared memory that is available for 
the application to use. 

If share_size is nonzero, this is the start address In 
host memory of the shared memory; otherwise it is 
undefined. 

If share_size is nonzero, this is the start address In 
TMS340 memory of the shared memory; othen/vlse, 
it is undefined. 



stack._size 
share_mera_size 

share_host_addr 
share_gsp_addr 
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get_COnf ig Return Board Configuration 

disp_j)itch Display pitch: linear difference between two scan 

lines in bits. 

disp_vres Vertical resolution in scan lines. 

disp_hres Horizontal resolution in pixels. 

screen_wide Contains the width of the monitor In centimeters. For 

systems where these dimensions are unknown, set 
to zero. 

screen_high Containsthe helghtofthemonitorincentimeters. For 

systems where these dimensions are unknown, set 
to zero. 

disp_j)size Pixel size. 

pixei_mask Contains a mask Of the bits used in a pixel. It normally 

contains the value of 2 to tlie power disp__psize minus 
1, indicating that every bit of pixel data is pertinent. 
On some boards the frame buffer may be arranged 
by 8 (dispjjsize = 8) but with only 6 bits implemented. 
In that case pixel mask would contain the value 63 
(hexadecimal 3F). 

paiet_gun_depth Number of bits per gun in palette. 

paiet_si2e Number of entries in the palette. 



palet^inset 



num_j)ages 



For most systems this field Is set to 0. For 
TMS34070-based boards that store the palette in the 
frame buffer, this is the offset from the start of the scan 
line to the first pixel data. 

Number of display pages in multi-buffered systems. 



num_of f scrn_areas This is the number of offscreen memory blocks avail- 
able. If nonzero, then it is used to allocate space for 
the offscreen array, which can be obtained from the 
TMS340 via a call to the get__offscreen_memory 
function. 



wksp_addr 



wksp_pitch 



Starting linear address in memory of offscreen work- 
space area. 

Pitch of offscreen workspace area. If wkspj3itch=0, 
then no offscreen workspace is currently allocated. 



Example See draw line. 
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TIGA Application Interface 



Return Current Cursor State get_CUrs_State 

Syntax int get_curs_state ( ) 

Type Core 

Description The get_curs_state routine returns true (nonzero) if the cursor is enabled, 
false otherwise. 

Example See cursor manipulation in set_curs_shape. 
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get_CUrs_xy Return Current Cursor Position 

SyntBX void get_curs_xy (px, py) 

short far *px; 
short far *py; 

Type Core 

Description The get_curs_xy returns the pixel coordinates of the cursor hotspot. 
Note that the coordinates are relative to the left corner of the screen, not 
to the drawing origin. 

Example See cursor manipulation in set_curs_shape. 
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Return Current Graphics Environment get_env 



Syntax 



Type 



typedef struct 

{ 

long xyorigin; 
long pensize; 
long patnaddr; 
long srcbm; 
long dstbm; 
unsigned long stylemask 
} ENVIRONMENT; 

void get_env(env) 

ENVIRONMENT far *env; 

Extended 



Description The get_env function takes as its argument a pointer to tlie ENVIRON- 
MENT structure containing the graphics environment variables. Although 
there are functions to manipulate these variables individually, if required, 
this function can be used to return the entire environment. Note that the 
structure described above may change in subsequent revisions. Therefore, 
it is recommended that the elements of the structure be referenced symboli- 
cally by their field name, rather than as an offset to the start of the structure. 
Insert files are available to do this.The fields of this structure are as follows: 

xyorigin Current drawing origin in y::x format set by set_draw_origln. 

pensize Current pen size arranged in y::x format, set by set_pensize. 

patnaddr TMS340 address of current pattern, set by set_patnaddr. 

srcbm TMS340 address of current source bitmap structure, set by 

set_srcbm. 

dstbm TMS340 address of current destination bitmap structure, set 

byset_dstbm. 

stylemask Current line style mask used by styledjine function. 
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get_fontinf O Return Installed Font Information 

Syntax typedef struct 

{ 

char facename[32] ; 

short first; /* ASCII code of first character */ 

short last; /* ASCII code of last character */ 

short maxwide; /* maximum character width */ 

short avgwide; /* average width of characters */ 

short maxkern; /* max character kerning amount */ 

short charwide; /* character width (O=proportional) */ 

short charhigh; /* character height */ 

short ascent; /* ascent (how far above base line) */ 

short descent; /* descent (how far below base line) */ 

short leading; /* Idng. (row bottom to next row top) */ 

long fontptr; /* font address in GSP memory */ 

short id; /* id of font (set at install time) */ 
}FONTINFO; 

int get_fontinfo(id/ pFontlnfo) 
short id; 
FONTINFO far *pFontInfo; 

Type Core 

Description The get_fontlnfo function copies a structure of type FONT! NFO, wliicli de- 
scribes the piiysical ciiaracteristics of tlie installed font referenced by id 
into the structure pointed to by pFontinf o. A nonzero value is returned if 
the structure is successfully copied; zero otherwise. An id of zero returns 
the FONTINFO structure for the system font, which does not need to be 
installed. If id is specified as -1 , the FONTINFO of the currently selected 
font is returned. 
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Return Interrupt Service Routine Priorities get_isr_priorlties 

Syntax void get_isr_priorities(numisrs, ptr) 

short numisrs; /* number of isrs */ 

short far *ptr; /* pointer to array of shorts */ 

Type Core 

Description The getJsr_prlorities function returns the priorities assigned when install- 
ing interrupt service routines (ISRs) using the instalLrIm or instali_alm 
functions. The calling function must ensure that enough space is allocated 
to hold all returned priority information. 

There is a one-to-one correspondence between an ISR and its associated 
priority. The first priority returned corresponds to the first ISR installed and 
soon. 

After calling this function, all priority data is flushed internally within TIGA, 
thereby enabling new priority data to be collected the next time instail_alm 
or instalLrIm is called to install an ISR. 

For more details on extensibility and the use of this function, refer to Chapter 
4. 
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get_mocleinfO Return Board Configuration 

Syntax int get_modeinfo (index, modeinf o) 

short index; 
MODEINFO far *modeinfo; 

Type Core 

Description The get_mocieinf o function returns a structure containing a possible board 
configuration supported by the current board and monitor. The MODEINFO 
structure Is described In detail in the get_conf Ig function. The Index param- 
eter Is used to cycle through the different modes by setting it to 0, 1 , 2, etc. 
It returns the MODEINFO structure for modes 0, 1 , 2, etc. If an invalid Index 
Is entered, the function returns false (zero); otherwise, it returns true. The 
total number of possible modes can be found from the CONFIG structure 
using the get_config function. 



3-64 TIGA Application Interface 



Return Nearest Color in a Palette get_nearest_COlor 
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Syntax long get_nearest_color(r, g, h, i) 

char r; 
char g; 
char b; 
char i; 

Type Core 

Description The get_nearest_color function searches the current palette and detects 
the closest color value to that specified by the parameters. For a mono- 
chrome palette, it is simply the first index closest to i. For color palettes, 
the function is more complicated. Weighting values are given to each index 
that are the sum of the differences between the parameter r and the color's 
red value, and the difference between the parameter g and the color's green 
value, etc. Then the index with the smallest weight value is returned. See 
also Appendix B.7 for details on color selection. 

Example See f unctionjmplemented. 
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get_OffSCreen_ITlGniory Return Offscreen h/lemory Blocks 



Syntax 



Type 



typedef struct 
{ 

long addr; 

short xext; 

short yext; 
} OFFSCREEN_AREA; 

void get_offscreen_memory (num_blocks, offscreen) 
short num_blocks; 
OFFSCREEN_AREA far *off screen; 

Core 



Description The get_offscreen_memory function returns the description of the off- 
screen memory bioci^s found in the system for the application to use. These 
blocl<s generally consist of display memory not being used either for the 
frame buffer or for an alternate page of frame buffer in multiple buffer sys- 
tems. The number of blocks is in the structure returned in get_config. The 
application must reserve enough room for that amount of offscreen entries 
by first calling Microsoft's C malloc. The address returned by malloc should 
be submitted as the parameter to this function, as well as the number of 
blocks to be returned. 

The structure returned consists of the start address of the TMS340 off- 
screen block, plus xext and yext in pixels. 

These offscreen blocks can be used as temporary workspace for functions 
such as set_wksp, seed_fill and zoom_rect. Note that no memory man- 
agement is performed on these blocks. The application must ensure the va- 
lidity of the data stored there. Note also that the offscreen memory blocks 
are completely separate from those used by the memory management func- 
tions such as gsp_malloc. 

If an offscreen memory block is used as the default offscreen workspace, 
it is guaranteed to be the first block returned via the 
get_offscreen_memory function. 
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TIGA Application Interface 



Return Offscreen Memory Blocks get_Off SCreen_memory 
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Example #include <malloc.h> 

#include <typedefs.h> 
#include <tiga.h> 
#include <extend.h> 

CONFIG config; 

short arrow_shape [ ] = 

{ 

0x0003, 0x0007, OxOOOF, OxOOlF, 0x003F, OxOOVF, OxOOFF, OxOlFF, 
OxOSFF, OxOlFF, OxOOVF, 0x00F7, OxOOF2, OxOlEO, OxOlEO, OxOOCO 

}; 

fdefine ARROW_W 16 
#define ARROW_H 16 

main ( ) 
{ 

int i; 

PTR arrow_addr; 
long arrow_size; 
OFFSCREEN_AREA far *of f screen; 

if (set_videomode(TIGA, INIT | CLR_S GREEN ) ) 
{ 

if (install_primitives () >= 0) 
{ 

get_config(&config) ; 

arrow_addr =0; 

/* check if any offscreen areas are big enough */ 

if ( config . mode . num_of f scrn_ar eas ) 

{ 

/* malloc space in host memory to hold offscreen */ 
/* structure */ 

offscreen = (OFFSCREEN_AREA *) malloc 
(config . mode . num_of f scrn_areas 
*si2eof (OFFSCREEN_AREA) ) ; 

/* get the offscreen memory data structure */ 
get_offscreen_memory (config. mode. num_offscrn_areas, 
offscreen) ; 



3-67 



get_Off SCreen_memory Return Offscreen Memory Blocks 



/* define size needed to store the arrow in bits */ 

arrow_size = ARROWJW * ARROW_H; 

for (i = 0; (i < config.mode.num_offscrn_areas) &S 

( ! arrow_addr) ; i++) 
{ 

if ( (offscreen [i] .xext * config.mode.disp_j)size) 
>arrow_size) 

arrow_addr=off screen [ i ] . addr ; 
} 
} 

/* if no available offscreen memory, use gsp_malloc */ 
if ( ! arrow_addr ) 

arrow_addr = gsp_malloc( (arrow_size+7) /8) ; 
/* transfer shape data from host to gsp */ 

host2gsp ( (uchar far *) arrow_shape, arrow_addr/ 

(arrow_size+7) /8, 0) ; 
/* set the source bitmap to the arrow shape */ 
set_srcbm(arrow_addr, ARROW_W, ARROW_W, ARROW_H, 1); 
/* blit the arrow to top-left corner of the screen, */ 
/* performing expand of 1 to n bits-per-pixel */ 
set_colors (LIGHT_GRAY, DARK_GRAY) ; 
bitblt (ARROW_W, ARROW_H, 0, 0, 0, 0) ; 
} 
set videomode (PREVIOUS, INIT) ; 
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Read an Entire Palette get_palet 

Syntax typedef struct; 

{ 

char r: 
char g; 
char b: 
char i; 
}PALET; 

void get_palet (palet_size, palet) 
short palet_size; 
PALET far *palet; 

Type Core 

Description The get_palet function reads an entire palette into the paiet array. The 
paiet_size parameter should be the same as the entry in the CONFIG 
structure to return the entire palette into the paiet array defined in host 
memory. 

Note that the paiet values returned are the physical colors used in the pal- 
ette on the board. If a palette hexadecimal entry is set by the set__palet or 
set_palet_entry functions to 

Red = FF 

Green = FF 

Blue = FF 

Intensity = OF 

With the actual color paiet using only 4 bits per gun, the hexadecimal values 
read by a call to get_palet or get_palet_entry are 

Red = FO 

Green = FO 

Blue = FO 

Intensity = 00 

See also Appendix B.7 for details on color selection. 

Example Seecalltoget_j)alet_entry. 
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get_palet_entry Return a Palette Entry 



Syntax int get_palet_entry (index, r, g, b, i) 

long index; 
char far *r; 
char far *g; 
char far *b; 
char far *i; 

Type Core 



Description The get_palet_entry routine returns the r, g, b, and i entries for a 
given entry in the palette. If the index is in the valid range, this function re- 
turns true (nonzero) and the palette entry. If the index is invalid, the values 
returned are also invalid, and the function returns false (zero). 
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Return a Palette Entry get_palet_entry 



Example finclude <typedefs.h> 
#include <tiga.h> 
#include <extend.h> 

CONFIG config; 

main ( ) 
{ 

char r, gl, g2, b, i; 

if (set_videomode(TIGA, INIT | CLR_S GREEN ) ) 
{ 

if (install_primitives >= 0) 

{ 

get_config(&config) ; 

if (function_impleinented(SET_PALET_ENTRY) ) 

{ 

/* set two logical colors, shades of green */ 

set_palet_entry (1, 0, OxFF, 0, 0) ; 

set_palet_entry(2, 0, OxFO, 0, 0); 

/* get the physical colors back */ 

get_j)alet_entry (1/ &r, &gl/ &b. Si); 

get_palet_entry (2, &r, &g2, &b. Si); 

/* if green values are the same, use blue instead */ 

if (gl == g2) 

{ 

set_palet_entry(2, 0, 0, OxFF, 0); 
} 

/* fill some rects based on these colors */ 
set_f color (1) ; 
f ill_rect (config . mode . disp_hres»l , 

config. mode. disp_vres»l, 0, 0); 
set_fcolor (2) ; 

f ill_rect ( config . mode . disp_hres»l , 
config. mode. di3p_vres»l, 
config . mode . disp_hres»l / 
config. mode. disp_vres»l) ; 
/* restore the palet */ 

init_palet ( ) ; 
} 
} 
set videomode (PREVIOUS, INIT) ; 
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get_pixel Return Pixel Value 

Syntax long get_pixel (x, y) 

short X, y; /* coordinates of pixel */ 

Type Extended 

Description The get_pixel function returns the value of the pixel at coordinates (x, y). 
The coordinates are relative to the drawing origin. Given a pixel size of n bits, 
the pixel is contained in the n LSBs of the return value (the MSBs are Os). 
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Return Plane Mask get_pmask 



Syntax long get_pmask ( ) ; 

Type Core 

Description The get_pmask function returns the value of the plane mask (GSP PMASK 
register). Although only the 16 LSBs of the PMASK register are im- 
plemented in the TMS34010, the plane mask is 32 bits to provide upward 
compatibility with future TMS340 processors. 

The plane mask designates which bits within a pixel are protected against 
writes, and affects all operations on pixels. The protected bits are replicated 
for each pixel throughout the 32-bit plane mask. The 1s in the plane mask 
specify protected bits in the destination pixel that cannot be modified, while 
the Os specify bits that can be altered. The plane mask can be altered with 
acall to the set_pmask function. Seethe TMS34010 User's Guideior afur- 
ther discussion of plane masking. 
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get_ppop Return Pixel Processing Operation 



Syntax int get_ppop() 

Type Core 

Description The get_ppop function returns the code for the current pixel processing op- 
eration (the PROP field in the TMS34010's Control register). The 5-bit 
PPOP code resides in the 5 LSBs of the return value; all higher order bits 
are Os. 

The PPOP code determines the manner in which pixels are combined (log- 
ically or arithmetically) during drawing operations. A new PPOP code can 
be selected with the set_ppop function. Legal PPOP codes are in the range 
0to21. 

Table 3-1. Pixel Processing Options 



Code 


Replace Destination Pixel with: 


Code 


Replace Destination Pixel with: 





source 


11 


NOT source AND destination 


1 


source AND destination 


12 


all Is 


2 


source AND NOT destination 


13 


NOT source or destination 


3 


alios 


14 


source NAND destination 


4 


source OR NOT destination 


15 


NOT source 


5 


source EQU destination 


16 


source + destination 


6 


NOT destination 


17 


ADDS (source, destination) 


7 


source NOR destination 


18 


destination - source 


8 


source OR destination 


19 


aUBS (destination - source) 


9 


destination 


20 


MAX (source, destination) 


10 


source XOR destination 


21 


MIN (source, destination) 



The effects of the 22 different codes are described in the TMS34010 User's 
Guide. 

Example See call to set_ppop in drawjine. 
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TIGA Application Interface 



Return Text Rendering Attributes get_textattr 
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Syntax int get_textattr(pControl, count, arg) 

char far *pControl; 
short count; 
short far *arg; 

Type Extended 

Description The getjextattr function gets text rendering attributes, pcontroi is a 
control string specifying the attributes to be retrieved. Values associated 
with each requested attribute are stored in order in the array specified by 
arg. The number of attributes in the control string is passed in parameter 
count. The number of attributes successfully assigned is returned. This is 
the current list of valid attributes: 

Attribute Description Option Value 

%a alignment = topleft,1=baseline 

%e additional intercharacter spacing 16-bit signed integer 
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get_transp Return Transparency 
Syntax int get_transp(); 

Type Core 

Description The get_transp function returns the state of the transparency enable bit 
(the T bit from the TMS340's control register). A value of true (nonzero) is 
returned if transparency is enabled; othenwise, false (zero) is returned. 

Transparency is an attribute that affects text drawing and pattern fills. If 
transparency is enabled, and the result of a pixel processing operation is 0, 
the destination pixel is not altered. If transparency is disabled, the destina- 
tion pixel is replaced by the result of the pixel processing operation, regard- 
less of the value of that result. See TMS34010 User's Gu/c/efor afurther dis- 
cussion of transparency. 
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Get Address at a TMS340 Trap Vector get_vector 

Syntax unsigned long get_vector (trapnum) 

unsigned short trapnum; 

Type Core 

Description The get_vector function returns the address currently in the trap vector 
specified by trapnum. This function should be used whenever it is neces- 
sary to read a trap vector address. 
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get_Videoinode Return Current Emulation Mode 
Syntax int get_videoinode ( ) ; 

Type Core 

Description The get_videomocle function returns thecurrent emulation mode. Possible 
emulation modes are discussed in the set videomode function. 
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Return Windowing Mode get_winclOWing 



Syntax int get_windowing ( ) ; 

Type Core 

Description The get_windowing function returns the 2-bit windowing code contained 
in the control I/O register. The windowing codes are 

00 No windowing 

01 Interrupt request on write in window 

1 Interrupt request on write outside window 

11 Clip to window 

For a more detailed description of the windowing operation, refer to the 
TMS34010 User's Guide. 
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get_Wksp Return Offscreen Workspace 



Syntax short get_wksp(addr, pitch) 

unsigned long *addr; /* pointer to workspace address */ 
unsigned long *pitch; /* pointer to workspace pitch */ 

Type Core 

Description The get_wksp function returns the parameters defining the current off- 
screen worl<space. The function returns false(zero) if no offscreen work- 
space is currently allocated. True (nonzero) is returned if a valid offscreen 
workspace is present. If true is returned, then the address and pitch of the 
offscreen workspace is returned through the addr and pitch pointer pa- 
rameters, respectively. 

When using functions, such as f ill_polygon, that require an offscreen work- 
space, check for a valid offscreen workspace by calling get_wksp. If none 
is present, then allocate one using gsp_malloc and update the workspace 
parameters via the set_wksp function. 

Example See fillj)olygon. 



3-80 TIGA Application interface 



Copy from GSP Memory to Coprocessor Memory gsp2cop 

Syntax void gsp2cop(copid,gspaddr,copaddr, length) 

short copid; 
long gspaddr; 
long copaddr; 
long length; 

Type Core 

Description The gsp2cop function copies data from TMS340 space into the coproces- 
sor space with ID copid (a number from — 7, with 4 being broadcast, 
as defined in the TI\/1S34020 User's Guide). The size of the data to be 
transferred is in 32-bit long words. 
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gsp2gsp Copy from GSP Memory to GSP Memory 

Syntax void gsp2gsp(addrl, addr2, length) 

long addrl; 
long addr2; 
long length; 

Type Core 

Description The gsp2gsp function copies length bytes from TMS340 memory to 
TMS340 memory. It handles overlapping regions. There is no restriction on 
the alignment of the address. 
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Move Data from GSP Memory to Host Memory gsp2hOSt 

Syntax void gsp2host (gptr, hptr, length, swizzle) 



long gptr; /* 


GSP memory pointer 


*/ 


char far *hptr; /* 


host memory pointer 


*/ 


unsigned short length; /* 


length in bytes 


*/ 


short swizzle; /* 


data SWIZZLE flag 


*/ 


Core 







Type 

Description The gsp2host function copies length number of bytes from TMS340 
memory pointed to by gptr to iiost memory at hptr. If swizzle is nonzero, 
tiie data is swizzled before it is written to the host (that is, the order of the 
bits in each byte is reversed), gptr is a pointer to TMS340 memory. It must 
be byte-aligned (that is, 3 LSBs must be 0). hptr is a pointer to host memory. 
It must be declared as a long pointer (for example, segment:offset format). 
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gsp2hOStxy Copy Rectangular Memory 

Syntax void gsp2hostxy(saddr, sptch, daddr, dptch, sx, sy, dx, dy, 

xext, yext, psize, swizzle) 
long saddr; 
long sptch; 
char far *daddr; 
long dptch; 
short sx; 
short sy; 
short dx; 
short dy; 
short xext; 
short yext; 
short psize; 
short swizzle; 

Type Core 

Description The gsp2hostxy function transfers a rectangular areafrom TMS340 to host 
memory. The area is extracted from the source bitmap starting at address 
saddr in TMS340 memory and is xext by yext pixels, with the pixel size 
being psize. The area starts at coordinates (sx, sy) in the source bitmap 
and is transferred to coordinates (dx, dy) of the destination bitmap. Be- 
cause the host memory address is restricted to be byte address aligned, the 
rectangular area sent is always padded on every side (if necessary) to en- 
sure that the data sent is aligned to the nearest byte boundary. The source 
pitch, spitch, is the difference in the linear addresses between two pixels 
in the same column and adjacent rows of the bitmap in TMS340 memory. 
dpitch is the same for host memory. 

If swizzle is nonzero, the data is swizzled before it is written to the host 
(that is, the order of the bits in each byte is reversed). 

This function has three restrictions placed upon it: 

Q The source pitch (on the TMS340 side), though a long variable, must 
be less than 16 bits. 

Q All data in the host array must be accessible from the segment address 
of daddr ; that is, none of the data being transferred must have a host 
address that crosses segment boundaries. 

Q If data is being swizzled, it is transferred from TMS340 to host and then 
transferred back again. The integrity of the data is preserved only if it 
is transferred back to the same address it came from. OthenA/ise, the 
data may be garbled. 
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Clear and Allocate GSP Memory gsp_cal lOC 
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Syntax long gsp_calloc (nmemb, size) 

long nmeinb; /* number of items to allocate */ 

long size; /* size (in bytes) of each item */ 

Type Core 

Description The gsp.cailoc function allocates a packet of TMS340 memory large 
enough to contain nmemb objects of the specified size and returns a pointer 
to it. If it cannot allocate the packet (that is, if it runs out of memory), it returns 
a null pointer (0). This function also initiates the allocated memory to all zer- 
os. This function is used in conjunction with gsp_free, gsp_malloc, 
gsp_minit, and gsp.realloc. 
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gsp_execute Execute a COFF Program 

Syntax void gsp_execute(entry_j>oint) 

unsigned long entry_point; 

Type Core 

Description The gsp_execute function is not of general use to a TIGA application but 
is included here because the capability to load the graphics manager is an 
integral part of TIGA. As a side effect of this TIGA provides a portable COFF 
loader across all TMS340 boards. This function executes a program that 
has been loaded by the loadcoff function. The parameter entry_point 
specifies the start address of the program. On most TMS340 boards, this 
address loads into the NMI vector and an NMI is performed. 

Example # include <tiga.h> 

main(argc, argv) 
int argc; 
char *argv [ ] ; 
{ 

unsigned long entry; 

if (argc == 2) 

{ 

if (cd_is_alive() ) 
{ 

if (entry = loadcoff (argv [1] ) ) 

gsp_execute (entry) ; 
else 

printf ("Error in load\n") ; 
} 

else printf ("TIGACD not running\n") ; 
} 

else printf ("Usage: load <coff filename>\n") ; 
} 
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Free GSP Memory from Allocation gsp_f ree 



Syntax 


int gsp_f ree (ptr) 
long ptr; 


Type 


Core 



Description The gsp_free function routine deallocates a packet of TMS340 memory 
(pointed to by ptr) previously allocated by gsp_malloc, gsp_calloc, or 
gsp_realloc. The function takes no action and returns false (zero) when an 
attempt is made to free a packet not previously allocated. This function re- 
turns true (nonzero) if the function sucessfuliy frees a valid TMS340 pointer. 

Example See draw_ovalarc. 
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gsp_mallOC Allocate GSP Memory 



Syntax long gsp_malloc( size) 

long size; /* size (in bytes) of block */ 

Type Core 

Description The gsp.malloc function allocates a packet of TMS340 memory of a speci- 
fied size and returns a pointer to it. If gsp_malloc is unable to allocate the 
packet (that is, if it runs out of memory), it returns a null pointer (0). This func- 
tion does not modify the memory it allocates. This function is used in con- 
junction with gsp_free, gsp_minit, and gsp.realloc. 



Example See fill_polygon. 
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Return Largest Free Block gsp_nfiaxheap 
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Syntax long gsp_maxheap ( ) 

Type Core 

Description The gsp_maxheap function returns the size of the largest contiguous 
block of program memory for heap allocation. It can be used at the start of 
an application to determine the total size of the available memory for heap 
allocation. If called during an application, it informs the application of the 
largest available block to download an object, for example, a bitmap. 
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gsp_minit Reinitialize Dynamic Memory Pool 

Syntax void gsp_ininit(stack_size) 

long stack size; 

Type Core 

Description The gsp_minit function reinitializes and frees all pointers in the TMS340 
dynamic memory in the heap pool. Any previously allocated blocks are no 
longer allocated, and all pointers to such blocks become invalid after this 
procedure is called. It can also be used to modify the stack_size. The de- 
fault stack size is defined in the CONFIG structure. Supplying an argument 
of -1 selects this stack size. Select a larger/smaller stack by supplying the 
stack size in bits. 

Be careful using this function because all allocated blocks of memory are 
freed, possibly including the background save area for the cursor (if stored 
in heap). Disable thecursorpriorto calling thisfunction and install a new cur- 
sor via a call to set_curs_shape aftenA/ard. If the workspace set by the 
set_wksp function was previously allocated in heap, it will have to be reset 
before using it. gsp.minit also frees data associated with downloaded 
extensions and interrupt service routines. Therefore, any required 
extensions or interrupt handlers must be reloaded after calling gsp_minit. 
This function is used in conjunction with gsp__free, gsp_malloc, and 
gsp__realloc. 
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TIGA Application Interface 



Reallocate GSP Memory gsp_real lOC 

Syntax long gsp_realloc (ptr, size) 

long ptr; /* pointer to object to change */ 

long size; /* new size (in bytes) of packet */ 

Type Core 

Description The gsp_realIoc function changes the size of the allocated data area 
pointed to by the first argument, ptr, to the size specified by the second 
argument. It returns a pointer to the space allocated since the packet and 
its contents may have to be moved to expand. Any memory freed by this op- 
eration is deallocated. If an error occurs, the function returns a zero. This 
function is used in conjunction with gsp.calloc, gsp_free, gsp_malloc, 
and gsp_minit. 
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hOSt2gsp Move Data from Host Memory to GSP Memory 
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Syntax void host2gsp (hptr, gptr, length, swizzle) 

char far *hptr /* host memory pointer */ 

long gptr; /* GSP memory pointer */ 

unsigned short length /* length in bytes */ 

short swizzle /* data SWIZZLE flag */ 

Type Core 

Description The host2gsp function copies length number of bytes from tlie host 
memory pointed to by hptr, to TI\/IS340 memory at gptr. If swizzle is non- 
zero, the data is swizzied before it is written to the Ti\/IS340 (that is, the 
order of the bits in each byte is reversed), hptr is a pointer to host memory 
and must be declared as a long pointer (that is, segment:offsetformat). gptr 
is a pointer to TMS340 memory. It must be byte aligned (that is, 3 LSBs must 
be 0). 

Exampie See get_offscreen_memory. 
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Copy Rectangular Area from Host to GSP hOSt2gspxy 
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Syntax void host2gspxy(saddr, sptch, daddr, dpitch, sx, sy, dx, dy, 

xext, yext/ psize, swizzle) 
char far *saddr; 
long sptch; 
long daddr; 
long dptch; 
short sx; 
short sy; 
short dx; 
short dy; 
short xext; 
short yext; 
short psize; 
short swizzle; 

Type Core 

Description The host2gspxy function transfers a rectangular area from host to TMS340 
memory. The area is extracted from the source bitmap starting at address 
saddr in host memory and is xext by yext pixels, with the pixel size being 
psize. The area starts at coordinates (sx, sy) in the source bitmap and is 
transferred to coordinates (dx, dy) of the destination bitmap. Because the 
host memory address is restricted to be byte address aligned, the rectangu- 
lar area sent is always padded on every side (if necessary) to ensure that 
the data sent is aligned to the nearest byte boundary.The source pitch, 
spitch, is the difference in the linear addresses between two pixels in the 
same column and adjacent rows of the bitmap in host memory. The destina- 
tion pitch dpitch is the same for TMS340 memory. 

If swizzle is nonzero, the data is swizzled before it is written to the TMS340 
(that is, the order of the bits in each byte is reversed). 
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initjpalet Default Palette 
Syntax void init_palet() 

Type Core 

Description The init__palet function initializes tlie first 1 6 entries of the palette to the 
EGA default colors: 

index = Black index 8 = Dark Gray 

index 1 = Blue index 9 = Light Blue 

index 2 = Green index 10 = Light Green 

index 3 = Cyan index 11 = Light Cyan 

index 4 = Red index 1 2 = Light Red 

index 5 = Magenta index 13= Light IVIagenta 

index 6 = Brown index 14= Yellow 

index 7 = Light Gray index 15= White 

The palette may well contain more than 16 entries. If so, this function repli- 
cates these 1 6 colors through the rest of the palette. 

Example See get_palet_entry. 
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Initialize Text Drawing Environment inlt_text 
Syntax void init_text() 

Type Core 

Description The init_text function removes all installed fonts from the font table and se- 
lects the OEM system font for use in subsequent text operations. It also re- 
sets all text drawing attributes to their default state. 
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instalL aim install Absolute Load Module 
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Syntax int install_alm(alm_name) 

char far *alm_name; /* load module filename */ 

Type Core 

Description The instalLalm function installs the absolute load module (specified by the 
function aim_name) Into theTIGA graphics manager and returns a module 
identifier which is used to invoke the extensions specified in the TIGAEXT 
section. 

If the module contains interrupt service routines, they will be Installed into 
TIGA, and the priority information associated with each can be retrieved 
once installation Is complete, with a call to getJsr_priorlties, which returns 
a priority list for last block of ISRs installed. For more details on extensibility 
and the use of this function, refer to Chapter 4. 

If an error occurs, a negative error code number is returned. Otherwise a 
module identifier is returned. This module identifier should be used whenev- 
er a routine contained within this module is specified, by joining the identifier 
with the routine number and command type using the bitwise-OR operator 
(I). 

These are the error codes returned by this function: 
Description 



Error 
Code 

-1 



-3 

-4 
-5 
-8 



System Error - Could not find tigalnk in main TIGA directory; 
either the TIGA environment variable -m option is not set, or that 
directory does not contain tigalnk.exe. 

Out of l\/lemory - Not enough host memory to run tigalnk or not 
enough TMS340 memory to store ALM. 

Communications Driver not Running - Run tigacd 

Graphics Manager not Running - Run tigalnk -ix 

Missing ALM - Either the spelling of the ALM filename does not 
match the ALM filename in the current directory, or the -i option of 
the TIGA environment variable is not set up. 



Example See Section 4.3.2 on page 4-8. 
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TIGA Application Interface 



Install Font in Table install font 



Syntax short install_font (pFont) 

unsigned long pFont; 

Type Extended 

Description The install_font function installs the font pointed to by pFont into the font 
table and returns an identifier (ID) for the font that can be used to reference 
the font in subsequent text operations. 

Note that pFont is a pointer to a font already located in TMS340 memory. 
The lnstall_font function merely adds the address of the font to the font 
table. The font must first be loaded from disk by the host and downloaded 
lntoTMS340 memory. This is shown in the example. 

The ID returned is nonzero if the installation was successful. If unsuccesful, 
the reserved ID for the system font (zero) is returned. For further details on 
the font format see Appendix A. 
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install font install Font in Table 



Example #include <tiga.h> 

#include <typedefs.h> 
#include <extend.h> 
finclude <stdio.h> 
#inGlude <malloc.h> 

#define FONT_MAGIC 0x8040 

typedef struct 

{ 

ushort magic; 

long size; 
} FILEHDR; 

/*LOADINST_FONT() Load, install font and return ref. ID */ 
int loadinst_f ont (name) 
char *name; 
{ 

FILE *fp; 

FILEHDR fh; 

FONT *hpTmp; 

int id = 0; 

PTR gpTmp; 

/* Examine font hdr. magic num. If incorrect return 0. */ 

if (!(fp = fopen( name, "rb") ) ) return (0); 

fread( &fh, sizeof (FILEHDR) , 1, fp) ; 

if (fh. magic != FONT_MAGIC) 

{ 

fclose(fp); 

return (0) ; 
} 

/* Malloc font in host and target. Read font into host, */ 
/* then move to target and free host memory. */ 

if (hpTmp = (FONT*)malloc( (ushort) fh. size)) 
if (gpTmp = (PTR) gsp_malloc ( fh.size)) 
{ 

rewind (fp) ; 

fread( hpTmp, fh.size, 1, fp) ; 

host2gsp (hpTmp, gpTmp, fh.size, 0); 

free ( hpTmp) ; 
} 

/* If all is OK, then install the font. */ 

if (gpTmp) 

id = install_f ont (gpTmp) ; 
fclose(fp); 
return (id) ; 
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Install Extended Drawing Primitives install jsrimitives 

Syntax int install_primitives{) 

Type Core 

Description The mstall_primitives function is similarto acal! to instali_rlm and is used 
to download extended primitives such as drawjine etc. Before calling an 
extended primitive download them either by this command, or by installing 
a dynamic load module, that includes the primitives. For more details on ex- 
tensibility and the use of this function, refer to Chapter 4. 

If the extended primitives are currently installed when install_primltives is 
called, no action is performed. 

This function returns these error codes: 

Error Description 

Code 

-1 System Error - Could not find tigalnk in main TIGA directory, 
either the TIGA environment variable -m option is not set, or that 
directory does not contain tigalnk.exe. 

-3 Out of Memory - Not enough host memory to run tigalnk or not 
enough TMS340 memory to store RLM. 

-4 Communications Driver not Running - Run TiGACD. 

~5 Graphics Manager not Running - Run tigalnk -ix 

-7 Symbol File Error - I/O error obtained in accessing symbol file. 
The -m option of the TIGA environment variable is not set or the 
directory does not contain TIGA3 4 o.sYM, or the file is corrupt. In the 
latter case, recopy this file from your backup disk. 

-1 Symbol Reference- An unresolved symbol was referenced by the 
RLM. Determine the name either by producing a link map for the 
RLM or by invoking tigalnk from the command line. 

-12 Symbol Table Mismatch - The modules installed in the symbol 
table do not match those the TIGA graphics manager has installed. 
Reinitialize the modules by a call to flush_extended and install 
them again. 
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install_primitives install Extended Drawing Primitives 

Example #include <typedefs.h> 
#include <tiga.h> 
tinclude <extend.h> 

CONFIG config; 

main ( ) 
{ 

/* using INIT_GLOBALS does not initialize the heap, */ 
/* if the primitives were installed they still are */ 
if (set_videomode(TIGA, INIT_GLOBALS | CLR_SCREEN) ) 
{ 

/* install the optional TIGA extended primitives */ 

if (install_j)rimitives < 0) 

{ 

print f ("Cannot install extended primitivesXn") ; 
exit(O); 
} 

get_config(&config) ; 
set_f color (LIGHT_GRAY) ; 
draw_line(0/ 0, config. mode. disp_hres, 

config.mode.disp_vres) ; 
set_videomode (PREVIOUS, INIT) ; 
} 
} 
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Install Relocatable Load Module install rim 
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Syntax int install_rlm(rlm_name) 

char far *rlin name; /* load module filename */ 



Type Core 

Description The install_rlm function installs the relocatable load module (specified by 
rim_name) into TIGA and returns a module identifier that is used to invoke 
the extensions specified in the TIGAEXT section. 

If the module contains interrupt service routines, they are installed into the 
TIGA graphics manager. The priority information associated with each can 
be retrieved once installation is complete with a call to the function 
getJsr_priorities which returns a priority list for the last block of ISRs in- 
stalled. 

If an error occurs, a negative module number is returned. Otherwise a mod- 
ule identifier is returned. This module identifier should be used whenever 
a routine contained within this module is specified, by joining the identifier 
with the routine number and command type using the bitwise-OR operator 
(I). 

For more details on extensibility and the use of this function refer to Chapter 
4. 

This function returns these error codes: 

Error Description 

Code 

-1 System Error - Could not find tigalnk in main TIGA directory, 
either the TIGA environment variable -m option is not set or that 
directory does not contain tigalnk.exe. 

-3 Out of Memory - Not enough host memory to run tigalnk or not 
enough TMS340 memory to store RLM. 

-4 Communications Driver not Running - Run TiGACD. 

-5 Graphics Manager not Running - Run tigalnk -ix 

-6 Missing RLM - Either the spelling of the RLM filename does not 
match the RLM filename in the current directory or the -i option of 
the TIGA environment variable is not set up. 

"7 Symbol File Error - I/O error obtained in accessing symbol file. 
The -m option of the TIGA environment variable is not set or the 
directory does not contain TIGA340.SYM or the file is corrupt. In the 
latter case, recopy this file from your backup disk. 

-1 Symbol Reference- An unresolved symbol was referenced by the 
RLM. Determine the name either by producing a link map for the 
RLM or by invoking tigalnk from the command line. 
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install rim install Relocatable Load Module 

Error Description (continued) 

Code 

-1 2 Symbol Table Mis-match - The modules installed in the symbol 
table do not match those the TIGA graphics manager has installed. 
Reinitialize the modules by a call to flush_extended and install 
them again. 

Example See Section 4.3.1 on page 4-7. 



3-1 02 TIGA Application Interface 



Install User Error Handler install USererror 
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Syntax void install_usererror(function_name) 

void (far *function_name) (); 

Type Core 

Description The install_usererror function installs a user error function that is called 
when an error is found in the host communications. The default usererror 
function simply prints a message to the screen when an error occurs. The 
user can install another function to trap these errors and handle them ac- 
cordingly. The user error function expects the following parameters: 

usererror (conimand_number, error_code) 
unsigned short coinmand_number; 
short error_code; 

Current error codes: 

1 Timeout with TMS340 communication on trying to load new func- 
tion; that Is, a previous function has not completed. 

2 Timeout on waiting for TMS340 function to complete; that is, the 
function just invoked has not completed. 

3 Parameter allocation failure, not enough memory to allocate a buff- 
er to download data from the current function. 

Example finclude <typedefs.h> 
#include <tiga.h> 
#include <extend.h> 

CONFIG config; 

#define nofpts 4000 
short lotofpts [nofpts*2] ; 

far usererror (command_number, error_code) 
unsigned short coinmand_nuinber; 
short error_code; 
{ 

printf ("TIGA error code of %d in command number %4x\n", 
error_code, command_number) ; 
} 
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install USererror install User Error Handier 



main ( ) 
{ 

int i, X, y; 



if (set_videomode(TIGA, INIT | CLR_SCREEN) ) 
{ 

if (install_priinitives () >= 0) 
{ 

get_config(&config) ; 

install_usererror (usererror) ; 

/* initialize nofpts points to some value */ 

X = y = 0; 

for (i =0; i < nofpts*2; ) 

{ 

lotofpts [i++] = x; 
lotofpts[i++] = y; 
if (i % 4) 
{ 

if (x++ > config.mode.disp_hres) 
X = 0; 
} 

else 
{ 

if (y++ > config.mode.disp_vres) 
y = 0; 
} 
} 

/* set timeout value to 1 second */ 

set_timeout (1000) ; 
set_pensize (64, 64) ; 

/* tie up the GSP to get timeout since many points */ 
/* are being downloaded, use parameter alloc entry */ 
/* points to allocate a temporary command buffer */ 
/* for the data transfer from host to GSP */ 

pen_polyline_a (nofpts, lotofpts) ; 

/* wait for GSP side to finish (to producetimeouts) */ 
synchronize ; 
} 

set_videomode (PREVIOUS, INIT) ; 
} 
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Leftmost One Imo 
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Syntax 


int Imo (n) 




long n; 


Type 


Core 



/* 32-bit integer */ 



Description The Imo function calculates the bit number of the leftmost one in argument 
n. The argument is treated as a 32-bit number whose bits are numbered 
from to 31 , where bit is the LSB (the rightmost bit position) and bit 31 
is the MSB (the leftmost bit position). 

For nonzero arguments, the return value is in the range to 31 . If the argu- 
ment is 0, a value of -1 is returned. 

Example See fill_polygon. 
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loadCOff Load COFF File 

Syntax unsigned long loadcoff (filename) 

char far *filename; 

Type Core 

Description The loadcoff function is not of general use to a TIGA application but is 
included here because the capability to load the graphics manager is an 
integral part of TIGA. With this function TIGA provides a portable COFF 
loader across all TMS340 boards. This function loads the COFF file 
specified in the parameter. It returns false (zero) if an error occurs during 
the load; othenwise, it returns the entry point address of the program .The 
entry point can be passed to the gspjexecute function to execute the 
COFF file. 

Example See gspjexecute. 
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Return Status of Page Flipping page_busy 
Syntax short page_busy() 

Type Core 

Description The page_busy function is used in conjuction witii tlie pagejiip function 
to determine tine status of page flipping. page_busy returns true (nonzero) 
if page_f lip is called and the pages have not been flipped. OthenA/ise, false 
(zero) is returned. 

Example SeepageJIip. 
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page_f lip Set Display and Drawing Pages 

Syntax int page_f lip (display, drawing) 

short display; 
short drawing; 

Type Core 

Description The page.f lip function can be used if the num_pages entry in the CONFIG 
structure (described in Appendix A) is greater than 1, indicating that multiple 
frame buffers are available in a particular configuration. This function sets 
the display page to display a particular frame buffer and sets the drawing 
page for subsequent drawing operations. 

The switching of display and drawing pages is performed at the start of verti- 
cal blanking. 

If the function completes normally, It returns true (nonzero). If the display or 
drawing page is invalid, the function aborts and returns false (zero). 



3-108 TIGA Application Interface 



Set Display and Drawing Pages page_f I i p 

Example #include <stdio.h> 

finclude <typedefs.h> 
#include <tiga.h> 
tinclude <extend.h> 

fdefine TRUE 1 

#define BALL_WT 16 

fdefine BALL_HT 16 

tdefine XMIN 

#define YMIN 

fdefine XMAX (config.]:node.disp_hres-BALL_WT) 

fdefine YMAX (config.mode.disp_vres-BALL_HT) 

fdefine NUM_SPRITES 15 

typedef struct 
{ 

short x; 

short y; 
} SPRITE; 

CONFIG conf ig; 
MODEINFO modeinfo; 

short display_page =0; 
static SPRITE sprite [NUM_SPRITES] ; 
static short dx[NUM_SPRITES] ; 
static short dy [NUM_SPRITES] ; 

f lip_page ( ) 
{ 

display_page ''= 1; 

page_flip(display_page, l-display_page) ; 
} 

init_logic { ) 
{ 

register int i; 

srand(9) ; 

for (i = 0; i < sizeof (sprite) /sizeof (SPRITE) ; i++) 

{ 

sprite[i].x = randO % ( conf ig. mode. disp_hres - 32); 

sprite[i].y = randO % ( conf ig. mode. disp_vres - 32); 

dx[i] = (randO % 6) + 1; 

dy[i] = (randO % 5) + 1; 
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page_f lip Set Display and Drawing Pages 



build_screen ( ) 
{ 

register int i; 

set_fcolor (0) ; 

clearjpage (BLACK) ; 

for (i = 0;i < sizeof (sprite) /sizeof (SPRITE) ;i++) 

{ 

set_f color (i+1) ; 

fill_oval (16, 16, sprite [i] .x, sprite [i] .y); 
} 
} 

animate ( ) 
{ 

register int i; 

short tx, ty, tdx, tdy; 

for (i =0; i < sizeof (sprite) /sizeof (SPRITE) ; i++) 
{ 

tx = sprite[i].x; 

ty = sprite [i] .y; 

tdx = dx[i] ; 

tdy = dy[i]; 

if (tx >= XMAX && tdx > 0) tdx = -tdx; 

else if (tx <= XMIN && tdx < 0) tdx = -tdx; 

else if (ty >= YMAX && tdy > 0) tdy = -tdy; 

else if (ty <= YMIN && dy[i] < 0) tdy = -tdy; 

sprite[i].x += ( dx[i] = tdx ); 

sprite[i].y += ( dy[i] = tdy ); 
} 

while (page_busy ( ) ) ; 
build_screen ; 
flip_page(); 
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Set Display and Drawing Pages page_f lip 






main ( ) 
{ 

int mode, oldmode; 

if (set_videomode(TIGA, INIT | CLR_SCREEN) ) 
{ 

if (install_primitives() >= 0) 
{ 

get_config(&config) ; 
oldmode = config.current_mode; 

/* look for a mode with more than 1 display page */ 
mode =0; 

do get_modeinfo(mode, Smodeinf o) ; 
while ( (modeinfo.num_pages == 1) && 
(++mode < config.num_modes) ) ; 
if (modeinfo.num_j>ages > 1) 
{ 

/* set configuration to multiple pages mode */ 
set_config(mode, TRUE); 

/* update config structure for current mode */ 
get_conf ig (&conf ig) ; 
flip_page(); 
init_logic ( ) ; 
do animate () ; 
while (IkbhitO); 
getchO ; 
} 

if (mode != oldmode) 
{ 

/* restore old mode */ 

set_config (oldmode, TRUE); 
clear_f rame_buf f er (BLACK) ; 
} 
} 

set_videomode (PREVIOUS, INIT) ; 
} 
} 
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patnf ill_COnvex Pattern nil Convex 

Syntax typedef struct 

{ 

short x; 
short y; 
} POINTS; 

void patnf ill_convex (n, points); 
short n; 
POINTS far *points; 

Type Extended 

Description The patnfill_convex function fills a convex polygon with a pattern, given 
a list of points representing the vertices. To be drawn correctly, the polygon 
must be convex; that is, it should contain no concavities. A polygon must 
have at least three vertices to be visible. To ensure that the polygon Is 
closed, the first and last vertices should contain the same coordinates. The 
polygon is pattern-filled with the current pattern, which is drawn in the cur- 
rent foreground and background colors. 

The function requires two input arguments: 

^ The first argument, n, defines the number of vertices in the polygon. 

Q The second argument, points, is an array in which each pair of adja- 
cent 1 6-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

The patnf ill_convex function automatically culls back faces to support 3D 
applications. A polygon is drawn only if its front side Is visible, that is. If it is 
facing toward the screen. If the vertices are specified in counterclockwise 
order, the polygon is assumed to be facing away from the screen and is 
therefore not drawn. 

The back face test is done by first comparing vertices n - 2, n - 1 , and to 
determine whether the polygon vertices are specified in clockwise (front 
face) or counterclockwise (back face) order. This test relies on the polygon 
containing no concavities. If the three vertices are colinear, the back face 
test is made again using the next three vertices, n -1 , 0, and 1 . The test re- 
peats until three vertices are not colinear. If all the vertices are colinear, the 
polygon is invisible. 

This function is similar to the patnf ill_j)olygon function but is specialized 
for rapid drawing of convex polygons. 

The argument point s can be of any length. The application can easily over- 
flow the command buffer which is used by the host processor to send the 
function parameters to the TMS340. The size of the command buffer is in 
the CONFIG structure (described in Appendix A) returned by the get_con- 
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Pattern Fill Convex patnfill_COnvex 

figfunction. It isupto the applicationtocheckthatthe data sent will not over- 
flow this buffer. 

The number of points that can be sent Is given by the following formula: 

com_buffer_slze (In bytes) - 10 



n< 



An alternate entry point patnf ill_convex_a with the same parameterization 
is also supplied to check the size of the data to be sent. If the command buff- 
er overflows patnf lll_convex_a will attempt to allocate a temporary buffer 
In heap. In this way, the application Is freed from having to check the size 
of the data being transferred; however, the invocation of the function takes 
longer becuase the length of the data must be parsed. If there is not enough 
room to store the temporary buffer in TMS340 memory, the error function 
is invoked (which can be trapped by the install_usererror function). 
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patnf i il_OVal Pattern Fill Oval 

Syntax void patnf ill_oval(w, h, xleft, ytop) 

short w, h; /* width, height of enclosing rect. */ 

short xleft/ ytop;/* XY coordinates of top left corner */ 

Type Extended 

Description The patnfill_oval function fills an ellipse with the current pattern in the cur- 
rent foreground and background colors. The ellipse is in standard position, 
with its major and minor axes parallel to the coordinate axes. 

The ellipse is defined by the minimum enclosing rectangle in which it is in- 
scribed. Four arguments define the rectangle: 

□i The width w 

Q[ The height h 

Qi The coordinates of the top left corner (xleft, ytop) 

Example See similar call to patnfill_piearc. 
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Pattern Fill Pie Arc patnf ill_piearc 

Syntax void patnf ill_piearc (w, h, xleft, ytop, theta, arc) 

short w, h; /* width and height */ 

short xleft, ytop; /* top left corner */ 

short theta; /* starting angle (degrees) */ 

short arc; /* extent of angle (degrees) */ 

Type Extended 

Description The patnfill_piearc function fills a pie-shaped wedge with a pattern. The 
wedge is bounded by an arc and two straight edges. The arc is taken from 
an ellipse in standard position, with its major and minor axes parallel to the 
coordinate axes. The two straight edges are defined by lines connecting the 
end points of the arc with the center of the ellipse. The arc is filled with the 
current pattern in the current foreground and background colors. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

Q The width w 

Qi The height h 

Q The coordinates of the top left corner (xieft, ytop) 

The last two arguments define the limits of the arc: 

Qi The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun- 
terclockwise. 

□l The arc extent, arc, specifies the number of degrees (positive or nega- 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 
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patnf ill__piearc Pattern Fill Pie Arc 



imimm n mm mim m t s tmtimitiiimtisimMtsfatseiiammmisifi 

Example #include <typedefs.h> 
#include <tiga.h> 
finclude <extend.h> 

CONFIG config; 

/* nuniber of installed patterns */ 

#define PMAX 9 

typedef short PAT_ARY[16]; 

PAT_ARY patterns [PMAX] = 

{ 

/* PATTERN #0 */ 

{ 0x0000, 0x3FFC, Ox7FFE, 0x0006, 0x0006, 0xlFC6, 0x3FE6, 0x3066, 

0x3066, 0x33E6, 0x31C6, 0x3006, 0x3006, 0x3FFE, OxlFFC, 0x0000}, 

/* PATTERN #1 */ 

{0x0000, 0x0080, 0x0080, 0x0080, OxOlCO, OxOlCO, 0x7FFF, OxlFFC, 

OxOFF8, Ox03EO, 0x03E0, Ox07FO, 0x0630, 0x0C18, 0x0808, 0x0000), 

/* PATTERN #2 */ 

{ 0x0000, 0x0000, 0x0E38, 0x1f7c, 0x3FFE, 0x3FFE, 0x3FFE, 0x3FFE, 

OxlFFC, 0x0FF8, 0x07F0, 0x03E0, OxOlCO, 0x0080, 0x0000, 0x0000 }, 

/* PATTERN #3 */ 

{ OxOOOO, OxOlCO, 0xl9CC, Oxl88C, 0x0490, 0x02A0, Ox31C6, 0x3FFE, 

0x31C6, Ox02AO, 0x0490, 0xl88C, 0xl9CC, OxOlCO, 0x0000, 0x0000 ), 

/* PATTERN #4 */ 

{ 0x0420, 0x0420, 0x3FFC, 0x2424, 0x2424, 0xFC3F, 0x2004, 0x2004, 

0x2004, 0x2004, 0xFC3F, 0x2424, 0x2424, 0x3FFC, 0x0420, 0x0420 )/ 

/* PATTERN #5 */ 

{ 0x0101, 0x0101, 0x8282, 0x7C7C, 0x1010, 0x1010, 0x2828, 0xC7C7, 

0x0101, 0x0101, 0x8282, 0x7C7C, 0x1010, 0x1010, 0x2828, 0xC7C7 ), 

/* PATTERN #6 */ 

{ 0x0000, 0x0000, 0x0000, OxlFFO, OxlFFO, OxOABO, 0x1570, OxOABO, 

0x1570, OxOABO, 0x1570, OxOABO, 0x0000, 0x0000, 0x0000, 0x0000 }, 
/* PATTERN #7 */ 

{ 0x0000, 0XFE7F, 0xFE7F, 0xFE7F, 0xFE7F, OxFE7F, 0xFE7F, 0x0000, 

0x0000, Ox7FFE, 0x7FFE, 0x7FFE, 0x7FFE, 0x7FFE, 0x7FFE, 0x0000 ), 

/* PATTERN #8 */ 

{ OXF007, 0xF803, 0x9C03, OxOE07, 0x070B, 0xO39C, 0x03F8, 0x07F0, 

OxOFEO, OxlFCO, 0x39C0, Ox70EO, 0xE070, 0xC039, OxCOlF, OxEOOF ), 

}; 

static short angles[] ={33, 22, 50, 16, 24, 60, 75, 55, 58}; 
/* Initialize pattern structure */ 

PATTERN patn = 

{ 

16,16,1,0L /* width, height, depth, data ptr */ 

}; 
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Pattern Fill Pie Arc patnf ill_piearc 



main ( ) 
{ 

short w, h/ X, y, theta, arc, i; 

PTR gsp_patterns; 

if (set_videomode(TIGA, INIT | CLR_SCREEN) ) 

{ 

if (install_primitives () >= 0) 

{ 

get_config(&config) ; 

/* allocate space for patterns in GSP memory */ 

gsp_j)atterns = gsp_malloc (PMAX * sizeof {PAT_ARY) ) ; 

/* download patterns from host to gsp */ 

host2gsp ( (char far *) patterns, gsp_patterns, 

PMAX * sizeof (PAT_ARY) , 0) ; 
/* setup up with rectangle for the piechart */ 
w = config.mode.disp_hres»l; 
h = config.mode.disp_vres»l; 
X = config.mode.disp_hres»2; 
y = config.mode.disp_hres»2; 
setjDColor (BROWN) ; 
set_f color (GREEN) ; 
theta = angles [0]; 

/* draw a piechart with pies filled with patterns */ 
for (i =1; i < 9; ++i) 
{ 

arc = angles [i]; 

patn.data = gspjpatterns + ((long)i«8); 

set_patn ( (char far*) Spatn) ; 

patnf ill_piearc (w, h, x, y, theta, arc) ; 

theta += arc; 

} 

set_f color (CYAN) ; 

f rame_oval (w, h, x, y, 2, 2); 

} 

set_videomode (PREVIOUS, INIT) ; 
} 



3-117 



patnf ill_polygon Pattern FHI Polygon 



Syntax typedef struct 

{ 

short x; 
short y; 
} POINTS; 

void patnf ill_^olygon (n, points) 
long n; 
POINTS far *points; 

Type Extended 

Description The patnfiiLpolygon function fills a polygon with a pattern, given a list of 
endpoints of the polygon. No restrictions are placed on the shape of the 
polygons filled by this function: edges can cross each other, filled areas 
can contain holes, and two or more filled regions can be disconnected 
from each other. The polygon Is filled with the current pattern using the 
current foreground and background colors. To ensure that the polygon is 
closed, the first and last vertices should have the same coordinates. 

The function requires two input arguments: 

Q The first argument, n, defines the number of vertices in the polygon. 

Q The second argument, points, is an array in which each pair of adja- 
cent 1 6-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

This function also takes as an implied argument a 1 -bit representation of the 
frame buffer, which it uses as a temporary workspace. This workspace must 
be set up prior to invoking the patnfill_polygon function (via a call to the 
setjvksp function). 

The argument points can be of any length. The application can easily 
overflow the command buffer that is used by the host processor to send the 
function parameters to the TMS340. The size of the command buffer is in 
the CONFIG structure (described in Appendix A) returned by the get_con- 
f ig function. It is up to the application to check that the data sent will not over- 
flow this buffer. 

The number of points that can be sent is given by the following formula: 

com_buffer_size (in bytes) - 10 



n< 
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An alternate entry point, patnfill_polygon_a with the same parameteriza- 
tion, is also supplied to check the size of the data to be sent. If the command 
buffer overflows, patnfill_polygon_a attempts to allocate atemporary buff- 
er in heap. In this way, the application is freed from having to check the size 

TIGA Application Interface 



Pattern Fill Polygon patnflll_polygon 

of the data being transferred. There is a cost, however, in that the invocation 
of the function takes longer since the length of the data has to be parsed. 
If there is not enough room to store the temporary buffer in TMS340 
memory, the error function is invoked (which can be trapped by the in- 
stall_usererror function) 

Example See call to fill_polygon. 
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patnfill_rect Pattern Fill Rectangle 

Syntax void patnf ill_rect (w, h, xleft, ytop) 

short w, h; /* width and height of rectangle */ 
short xleft, ytop; /* XY coord at top left corner */ 

Type Extended 

Description The patnf ill_rectfunction fills a rectangle with the current pattern in the cur- 
rent foreground and background colors. Four arguments define the rectan- 
gle: 

Qi The width w 

Q The height h 

Qi The coordinates of the top left corner (xief t , ytop) 

Example See call to f ill_rect In fill_j)olygon example. 
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Pattern Frame Oval patnf rame_OVal 
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Syntax void patnf rame_oval (w, h, xleft, ytop, dx, dy) 

short w, h; /* width, height of rect. */ 

short xleft, ytop; /* coordinates at top left corner */ 

short dx, dy; /* width, height of frame border */ 

Type Extended 

Description The patnframe_oval function fills an ellipse-shaped frame with a pattern. 
The frame consists of a filled region between two concentric ellipses. The 
frame is filled with the current pattern in the current foreground and back- 
ground colors. The portion of the screen enclosed by the frame is not al- 
tered. 

The outer ellipse is specified in terms of the minimum enclosing rectangle 
in which it is inscribed. The first four arguments define the rectangle: 

Ql The width w 

Q The height h 

^ The coordinates of the top left corner (xleft, ytop) 

The thickness of the frame in the X and Y dimensions is defined by two addi- 
tional arguments: 

Ql dx specifies the horizontal distance between the outer and inner el- 
lipses. 

Ql dy specifies the vertical distance between the outer and inner ellipses. 

Example See similar call to f rame_oval in patnfill_piearc example. 
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patnf rame_rect Pattern Frame Rectangle 

Syntax void patnf rame_rect (w, h, xleft, ytop, dx, dy) 

short w, h; /* width, height of rect. */ 

short xleft, ytop; /* coordinates at top left corner */ 

short dx, dy; /* width, height of frame border */ 

Type Extended 

Description The patnf rame_rect function fills a rectangular frame with a pattern. The 
frame consists of a filled region between two concentric rectangles. The 
frame is filled with the current pattern in the current foreground and back- 
ground colors. The portion of the screen enclosed by inner edge of the frame 
is not altered. 

The first four arguments define the outer rectangle: 

Qi The width w 

□i The height h 

Q The coordinates of the top left corner (xief t , ytop) 

The thickness of the frame in the X and Y dimensions is defined by two addi- 
tional arguments: 

Q dx specifies the horizontal distance between the outer and inner rect- 
angles. 

Q dy specifies the vertical distance between the outer and inner rectan- 
gles. 
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Pattern Pen Line patnpenjine 

Syntax void patnpen_line(xl, yl, x2, y2) 

short xl, yl; /* starting coordinates */ 

short x2, y2 /* ending coordinates */ 

Type Extended 

Description The patnpenjine function uses the pen to draw a patterned line. Argu- 
ments xl and yl specify the starting coordinates of the line, and x2 and y2 
specify the ending coordinates. 

The pen is a rectangle whose width and height can be modified by means 
of the set_pensize function. At each point on the line drawn by the patn- 
penjine function, the pen is located with its top left corner touchingthe line. 
The area covered by the pen is filled with the current pattern in the current 
foreground and background colors. 
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patnpenjine Pattern Pen Line 

Example #include <typedefs.h> 
#include <tiga.h> 
#include <extend.h> 

CONFIG config; 

/* number of installed patterns */ 

fdefine PMAX 8 

typedef short PAT_ARY[16]; 

PAT_ARY patterns [PMAX] = 

{ 

/* PATTERN #0 */ 

{ OxAAFA, 0xFF77, OxFFFF, OxFF77, OxAAFA, 0x7070, 0xF8F8, 0x7070, 
OxFAAA, 0x77FF, OxFFFF, 0x77FF, OxFAAA, 0x7070, 0xF8F8, 0x7070 ), 

/* PATTERN #1 */ 

{ OxOOCO, 0x0030, 0xlF88, 0x2044, 0x4024, 0x4E24, 0x9124, 0xAlC4, 
0x2385, 0x2489, 0x2472, 0x2402, 0x2204, OxllFS, OxOCOO, 0x0300 )/ 

/* PATTERN #2 */ 

{ 0x93C9, OxOE70, 0xlC38, 0xB99D, OxF24F, 0x6656, 0xCDB3, 0x4DB2, 
0x4DB2, 0xCDB3, 0x6666, 0xF24F, 0xB99D, 0xlC38, OxOE70, 0x93C9 }, 

/* PATTERN # 3 */ 

{ 0x0000, Ox7FFE, 0x6426, 0x524A, 0x4992, 0x6666, 0x566A, 0x4992, 
0x4992, 0x566A, 0x6666, 0x4992, Ox524A, 0x6426, Ox7FFE, 0x0000 ), 

/* PATTERN #4 */ 

{ 0x0441, 0x8AA2, 0x5114, 0x2388, 0x5114, 0x8442, OxOEEl, 0xA54A, 
0x739C, 0XA54A, OxOEEl, 0x8442, 0x5114, 0x2388, 0x5114, 0x8AA2 }, 

/* PATTERN #5 */ 

{ 0x0000, 0x601E, 0x7C31, 0x2733, 0x29B3, 0x34B0, 0xl2B0, 0xl8B0, 

0x0F70, 0x00B2, 0xlFF4, 0x7FFC, 0x601C, 0x403C, 0x5842, 0x3800 }, 

/* PATTERN #6 */ 

{ 0x1111, 0x2222, 0x4444, 0x8888, 0x1111, 0x2222, 0x4444, 0x8888, 

0x1111, 0x2222, 0x4444, 0x8888, 0x1111, 0x2222, 0x4444, 0x8888 }, 

/* PATTERN #7 */ 

{ 0x8888, 0x4444, 0x2222, 0x1111, 0x8888, 0x4444, 0x2222, 0x1111, 
0x8888, 0x4444, 0x2222, 0x1111, 0x8888, 0x4444, 0x2222, 0x1111 ), 

}; 

/* Initialize pattern structure */ 

PATTERN pattern = 

{ 

16/16,1/OL /* width, height, depth, data ptr */ 

}; 
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Pattern Pen Line patnpenjine 



main ( ) 
{ 

long X, y; 

long r, t; 

short fcolor, colormax, patn; 

PTR gsp_patterns; 

if (set_videomode(TIGA, INIT | CLR_SCREEN) ) 
{ 

if (install_primitives >= 0) 
{ 

get_conf ig (Sconf ig) ; 

set_draw_origin (config.mode.disp_hres»l, 

config.mode.disp_vres»l) ; 

set_j)ensize(4, 3); 

/* allocate space for patterns in GSP memory */ 

gsp_patterns = gsp_malloc (PMAX * sizeof (PAT_ARy) ) ; 

/* download patterns from host to gsp */ 

host2gsp ((char far *) patterns, gsp_patterns, 

PMAX * sizeof (PAT_ARy) , 0) ; 
/* initialize colormax variable */ 

colormax = (l«config.mode.disp_psize) - 1; 
f color =1; 
patn =0; 

/* draw a swirling patterned shape */ 

for (r = 20; r < (config.mode.disp_vres»l) ; 

r += r » 4) 
{ 

X = 0; 

y = -r « 16; 

for (t = 0; t < 201; ++t) 

{ 

set_f color (f color) ; 

if (++fcolor == colormax) fcolor = 1; 

if (++patn == PMAX) patn = 0; 

pattern. data = gsp_patterns+( (long)patn«8) ; 

set_patn (spattern) ; 

patnpen_line(x-(x»2)»16, y-(y»2)»15, x»16, 

y»16) ; 
X -= y » 5; 
y += X » 5; 
} 
} 
} 
set videomode (PREVIOUS, INIT); 
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patnpen_OValarc Pattern Pen Oval Arc 



Syntax 



void patnpen_ovalarc (w, h, xleft, ytop, theta, arc) 



short w, h; 


/* width and height 


*/ 


short xleft, ytop; 


/* top left corner 


*/ 


short theta; 


/* starting angle (degree) 


*/ 


short arc; 


/* angle extent (degrees) 


*/ 



Type 



Extended 



Description The patnpen_ovalarc function uses the pen to draw a patterned arc of an 
ellipse. The ellipse is in standard position, with the major and minor axes 
parallel to the coordinate axes. 

The pen is a rectangle whose width and height can be modified by means 
of the set_pensize function. At each point on the arc drawn by the patn- 
pen_ovalarc function, the pen is positioned so that its top left corner 
touches the arc. The area covered by the pen is filled with the current pattern 
in the current foreground and background colors. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

Q The width w 

^ The height h 

Q The coordinates of the top left corner (xief t , ytop) 

The last two arguments define the limits of the arc: 

□i The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle, and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun- 
terclockwise. 

Q The arc extent, arc, specifies the number of degrees (positive or nega- 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 

Example See patnpenjine for use of patterned pen and draw_ovalarc for use oval 
arcs. 
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Pattern Pie Arc patnpen_piearc 

Syntax void patnpen_piearc(w, h, xleft, ytop, theta, arc) 

short w, h; /* width and height */ 

short xleft, 'ytop; /* top left corner */ 

short theta; /* starting angle (degree) */ 

short arc; /* angle extent (degree) */ 

Type Extended 

Description The patnpen_piearc function uses the pen to draw a patterned, pie-shaped 
wedge from an ellipse. The wedge is formed by an arc of the ellipse, and 
by two straight lines that connectthe two end points of the arc with the center 
of the ellipse. The ellipse is in standard position, with the major and minor 
axes parallel to the coordinate axes. 

The pen is a rectangle whose width and height can be modified by means 
of set_pensize function. At each point on the arc drawn by the patn- 
pen_piearc function, the pen is positioned so that its top left corner touches 
the arc. The two lines from the center are drawn in similar fashion. The area 
covered by the pen is filled with the current pattern in the current foreground 
and background colors. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

l^ The width w 

Q The height h 

Q The coordinates of the top left corner (xieft, ytop) 

The last two arguments define the limits of the arc: 

Q The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun- 
terclockwise. 

Qi The arc extent, arc, specifies the number of degrees (positive or nega- 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 

Example See patnpenjine for use of patterned pen and similar call to 
patnfill_piearc. 
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patnpen_point Pattern Pen Point 

Syntax void pat npen_point (x ,y) 

short X, y; /* pen coordinates */ 

Type Extended 

Description The patnpen_point function uses the pen to draw a patterned point. The 
resulting figure is a rectangle the width and height of the pen, filled with the 
current pattern in the currentforeground and background colors. The top left 
corner of the rectangle is located at coordinates (x, y) . 

Example See patnpenjine for use of patterned pen and draw_point for drawing 
single pixels. 
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Pattern Pen Polyline patnpen_polyline 



ssawssssssssssss! 



Syntax 



Type 



typedef struct points_struct 
{ 

short x; 

short y; 
} POINTS; 

void patnpen_j)oly line (ri/ points) 
short n; 
POINTS far *points; 

Extended 



Description The patnpen_poiyline function uses the current pen to draw n patterned 
lines whose endpoints are supplied in an array of structures, described 
in the syntax. 

The function requires two input arguments: 

Q The first argument, n, defines the number of vertices in the polygon. 

Qi The second argument, points, is an array in which each pair of adja- 
cent 1 6-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

The argument points can be of any length. The application can easily over- 
flowthe command bufferthat is used by the host processorto send the func- 
tion parameters to the TMS340. The size of the command buffer is in the 
CONFIG structure (described in Appendix A) returned by the get_config 
function. The application must checkthatthe data sent will not overflow this 
buffer. 

The number of points that can be sent is given by the following formula: 

com_buffer_size (in bytes) - 1 



n< 



Example 



An alternate entry point patnpen_polyline_a with the same parameteriza- 
tion, is also supplied to check the size of the data to be sent. If the command 
buffer overflows patnpen_polylme_a attempts to allocate a temporary 
buffer in heap. In this way, the application is freed from having to check the 
size of the data being transferred; however, the invocation of the function 
takes longer because the length of the data must be parsed. If there is not 
enough room to store the temporary buffer in TMS340 memory, the error 
function is invoked (which can be trapped by the install_usererror function) 

See patnpenjine for use of patterned pen and similar call to 
draw_polyline for use of polylines. 
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peek_breg Peek B Register 



Syntax long peek_breg (breg) 

short breg; /* B-file register number */ 

Type Core 

Description The peek_breg function returns the contents of a B-file register. Argument 
breg is a register number In the range to 15. The function ignores all but 
the 4 LSBs of breg. The return value is 32 bits. 
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Pen Line penjine 

Syntax void pen_line(xl, yl, x2, y2) 

short xl, yl; /* starting coordinates */ 

short x2, y2; /* ending coordinates */ 

Type Extended 

Description The penjine function uses the pen to draw a line. Arguments xi and yi 
specify the starting coordinates of the line; x2 and y2 specify the ending 
coordinates. 

The pen is a rectangle whose width and height can be modified by means 
of the set_pensize function. At each point on the line drawn by the penjine 
function, the pen is located with its top left corner touching the line. The area 
covered by the pen is solid-filled In the current foreground color. 

Example See install_usererror for similar call to pen_polyline . 
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pen_OValarc Pen OvalArc 

Syntax void pen_ovalarc (w, h, xleft, ytop, theta, arc) 

short w, h; /* width and height */ 

short xleft, ytop; /* top left corner */ 

short theta; /* starting angle (degrees) */ 

short arc; /* angle extent (degree) */ 

Type Extended 

Description The pen_ovalarc function uses the pen to draw an arc taken from an ellipse. 
The ellipse is in standard position, with the major and minor axes parallel 
to the coordinate axes. 

The pen is a rectangle whose width and height can be modified by means 
of the set_pensize function. At each point on the arc drawn by the 
pen_ovalarc function, the pen is located with its top left corner touching the 
arc. The area covered by the pen is solid-filled in the current foreground col- 
or. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

□i The width w 

□i The height h 

Qi The coordinates of the top left corner (xief t , ytop) 

The last two arguments define the limits of the arc: 

Qi The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun- 
terclockwise. 

Q The arc extent, arc, specifies the number of degrees (positive or nega- 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 

Example See instalLusererror for use of drawing pen and draw_ovalarc for use of 
oval arcs. 
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Pen Pie Arc pen_piearc 



Syntax 



void pen_piearc (w, h, xleft, ytop, theta, arc) 



short w, h; 
short xleft, 
short theta; 
short arc; 



/* width and height 
ytop; /* top left corner 

starting angle (degrees) 
angle extent (degrees) 






*/ 



Type 



Extended 



Description The pen_piearc function uses the pen to draw a pie-shaped wedge from 
an ellipse. The wedge is formed by an arc of the ellipse and by two straight 
lines that connect the two end points of the arc with the center of the ellipse. 
The ellipse is in standard position, with the major and minor axes parallel 
to the coordinate axes. 

The pen is a rectangle whose width and height can be modified by means 
of the set_pensize function. At each point on the arc drawn by the 
pen_piearc function, the pen is located with its top left corner touching the 
arc. The area covered by the pen is solid-filled in the current foreground col- 
or. 

The ellipse from which the arc is taken is specified in terms of the minimum 
enclosing rectangle in which it is inscribed. The first four arguments define 
the rectangle: 

Q The width w 

□i The height h 

Q The coordinates of the top left corner (xleft, ytop) 

The last two arguments define the limits of the arc: 

Q The starting angle, theta, is measured from the center of the right side 
of the enclosing rectangle, and is treated as modulus 360. Positive 
angles are measured clockwise; negative angles are measured coun- 
terclockwise. 

□i The arc extent, arc, specifies the number of degrees (positive or nega- 
tive) spanned by the angle. If the arc extent is outside the range 
[-359,+359], the entire ellipse is drawn. 

Both arguments are expressed in degrees of elliptical arc, with 360 degrees 
representing one full rotation. 

Example See instalLusererror for use of drawing pen and patnf ill_piearc for use 
of pie arcs. 
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penj30int Pen Point 

Syntax void pen_point (x, y) 

short X, y; /* pen coordinates */ 

Type Extended 

Description The pen_point function uses the pen to draw a point. The resulting figure 
is a rectangle the width and height of the pen and solid-filled with the current 
foreground color. The top left corner of the rectangle is located at coordi- 
nates (x, y). 

Exampie See install_usererror for use of drawing pen and drawjjoint for drawing 
single pixels. 
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Pen Polyline penj3olyline 



Syntax typedef struct 

{ 

short x; 
short y; 
} POINTS; 

void pen_polyline (n, points); 
short n; 
POINTS far *points; 

Type Extended 

Description The pen_polyline function uses the current pen to draw lines whose 
endpoints are supplied in an array of structures, described in the syntax. 

The function requires two input arguments: 

Q The first argument, n, defines the number of vertices in the polygon. 

□i The second argument, points, is an array In which each pair of adja- 
cent 1 6-bit quantities contains the X and Y coordinates, respectively, of 
a vertex. 

The argument point s can be of any length. The application can easily over- 
flow the command buffer used by the host processor to send the function 
parameters to the TMS340. The size of the command buffer is in the CON- 
FIG structure (described in Appendix A) returned by the get_config func- 
tion. The application must check that the data sent will not overflow this buff- 
er. 

The number of points that can be sent Is given by the following formula: 

com_buffer_size (in bytes) - 10 



n< 



An alternate entry point pen_polyline_a with the same parameterization, 
is supplied to check the size of the data to be sent. If the command buffer 
overflows pen_polyllne_a will attempt to allocate a temporary buffer in 
heap. In this way the application is freed from having to check the size of 
the data being transferred. There is a cost, however, in that the invocation 
of the function will take longer since the length of the data has to be parsed. 
If there is not enough room to store the temporary buffer in TMS340 
memory, the error function is invoked (which can be trapped by the in- 
stall_usererror function). 

Example See install usererror. 
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poke_breg Poke B Register 

Syntax void poke_breg (breg, value) 

long breg; /* B-file register number */ 

short value; /* 32-bit register contents */ 

Type Core 

Description The poke.breg function stores the 32-bit value In a B-flle register. Argu- 
ment breg Is any register number between and 15. 
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Rightmost One rmo 

Syntax int rmo(n) 

long n; /* 32-bit integer */ 

Type Core 

Description The rmo function calculates the bit number of the rightmost one in argument 
n. The argument is treated as a 32-bit number whose bits are numbered 
from to 31 , where bit is the LSB (the rightmost bit position) and bit 31 
is the MSB (the leftmost bit position). 

For nonzero arguments, the return value is in the range to 31 . If the argu- 
ment is 0, a value of -1 is returned. 
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seedjill seed nil 

Syntax int seed_f ill (xseed, yseed, buffer, maKbytes) 

short xseed, yseed; /* coordinates of seed pixel */ 

long buffer; /* GSP pointer to working storage */ 

short maxbytes; /* size of buffer in bytes */ 

Type Extended 

Description The seed_fill function fills a connected region of pixels starting at a speci- 
fied seed pixel. The seed color is the color of the specified seed pixel at the 
time the function is called. The connected region is solid-filled with the cur- 
rent foreground color. 

□i The first two arguments, xseed and yseed, specify the coordinates of 
the seed pixel. 

The last two arguments specify a buffer used as a working storage during 
the seed fill. 

Q Argument buffer is a buffer large enough to contain the temporary data 
that the function uses. 

Qi Argument maxbytes is the number of 8-bit bytes available in the buffer 
array. 

Storage requirements can be expected to Increase with the complexity of 
the connected region being filled. 

I 1 

Note: 

The argument buffer is a pointer in TMS340 memory. This area must have 
previously been allocated using gsp.malloc. 

The connected region filled by the function always includes the seed pixel. 
To be considered part of the connected region, a pixel must both match the 
seed color and be horizontally or vertically adjacent to another pixel that is 
part of the connected region. (A diagonally adjacent neighbor is not suffi- 
cient.) 

The seedjill function aborts (returns immediately) if any of these condi- 
tions are detected: 

Q The seed pixel matches the current foreground color. 

Q The seed pixel lies outside the current window register values. 

Q If at any point the storage buffer space specified by maxbytes is insuffi- 
cient to continue. 

lfthefunctionaborts,itreturnsthevaluefalse(zero);othenwise, It completes 
normally and returns true (nonzero). 

Example See draw__ovalarc. 
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Seed Pattern Fill seedj3atnfill 

Syntax int seed_patnf ill (xseed, yseed, buffer, maxbytes) 

short xseed, yseed; /* coordinates of seed pixel */ 

long buffer; /* GSP pointer to working storage */ 

short maxbytes; /* size of buffer in bytes */ 

Type Extended 

Description The seed_patnfill function fills a connected region of pixels witii a pattern 
starting at a specified seed pixel. The seed color is the color of the specified 
seed pixel at the time the function is called. The connected region is filled 
with the current pattern in the current foreground and background colors. 

Qi The first two arguments: xseed, yseed, specify the coordinates of the 
seed pixel. 

The last two arguments specify a buffer used as a working storage during 
the seed fill. 

^ Argument buffer is a buffer large enough to contain the temporary data 
that the function uses. 

□i Argument maxbytes is the number of 8-bit bytes available in the buffer 
array. 

Storage requirements can be expected to increase with the complexity of 
the connected region being filled. 

I ' 1 

Note: 

The argument buffer is a pointer in TMS340 memory. This area must have 
previously been allocated using gsp.malloc. 
' « 

The connected region filled by the function always includes the seed pixel. 
To be considered part of the connected region, a pixel must both match the 
seed color and be horizontally or vertically adjacent to another pixel that is 
part of the connected region. (A diagonally adjacent neighbor is not suffi- 
cient.) 

The seecl_patnfili function aborts (returns immediately) if any of these con- 
ditions is detected: 

Q The seed pixel matches the current foreground or background color. 

Qi The seed pixel lies outside the current window register values. 

Qi If at any point the storage buffer space specified by maxbytes is insuffi- 
cient to continue. 

lfthefunctionaborts,itreturnsthevaluefalse(zero);otherwise,itcompletes 
normally and returns true (nonzero). 

Example See similar call to seed_fill in draw_ovalarc. 
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select font Select installed Font for Use 
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Syntax int select_font( id ) 

short id; 

Type Extended 

Description The select.font function selects a previously installed font for use by the 
text functions. The input argument, id, must be either zero, indicating the 
system OEM font, or a value returned by the install_font function. 

A nonzero value is returned if the selection was successful, and a zero value 
if the font referred to by id is not installed in the font table. 
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Set Background Color set_bCOlor 

Syntax void set_bcolor (color) 

long color; 

Type Core 

Description The set_bcoIor function sets the COLOROB-file register to the color in- 
dex replicated by the pixel size of the current configuration. 



Example See patnfiil_piearc. 
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Set_Cllp_rect Set cupping Rectangle 

Syntax void set_clip_rect (w, h, xlef t , ytop) 

short w,h; /* width, height of clipping rect */ 

short xleft/ytop; /* coordinates of top left corner */ 

Type Core 

Description The set_cllp_rect function sets the current clipping rectangle by updating 
the B-file registers WSTART(B5) and WEND(B6) to the dimensions 
specified by the parameters passed. The parameters xief t and ytop are 
relative to the current drawing origin. 

Example See draw_oval. 
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Set Foreground and Background Colors set_COlors 

Syntax void set_colors(f color/ bcolor) 

long fcolor; 
long bcolor; 

Type Core 

Description The set_colors function sets both the C0L0R1 and COLORO B-f ile regis- 
ters to the color indices replicated by the pixel size of the current configura- 
tion. 

Example See get_offscreen_memory. 
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S6t_C0nfig initialize Graphics Configuration 

Syntax Int set_config(graphics_mode, init_draw) 

short graphics_mode; 
short init_draw; 

Type Core 

Description The set_config function sets the graphics mode selected by the index 
passed to the default graphics mode, in which the board remains until a 
subsequent call to set_config is made. Different modes can have different 
display resolutions, pixel sizes etc. The get_config function can be used 
to determine the number of board configurations available on a given board 
and the parameters for each configuration. The get_modeinf o function can 
be used to determine the particular configuration parameters for a given 
board.To select a particular mode, this function is invoked with an argument 
of the desired mode number. 

if the graphics_mode argument is valid, the new graphics mode is set up 
and the function returns true (nonzero). If the argument is invalid, the func- 
tion performs no operation and returns false (zero). 

This function initializes the following TMS340 registers: 

HESYNC to DPYCTL I/O registers Initialized for the current resolution. 

PSIZE I/O register Set to the current pixel size. 

CONVDP I/O register Set to the left-most-one of the dis- 

play pitch. 

DPYTAP I/O register Initialized for the board. 

DPTCH B-file register Set to the display pitch. 

OFFSET B-file register Set to the offset of the current draw- 

ing page. 

WSTART B-file register Set to 0. 

WEND B-file register Set to the disp_vres:disp_hres 

value. 

If there is an on-board palette, it is reset to the default colors (see 
initjsalet). 

The set_conf ig function also sets the display and drawing pages to page 
(for multiple-paged frame buffers). 
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Initialize Graphics Configuration set_COnf ig 

Furthermore if the init_draw flag is set to true (nonzero), the following 
drawing environments are initialized: 

Q The transparency is disabled (in CONTROL I/O register) 

□i Window clipping is set (in CONTROL I/O register) 

Q Pixel Processing is set to replace (in CONTROL I/O register) 

Oi PMASK I/O register is set to 

Q Foreground color is set to light grey and the background color to black 

Qi Source and destination bitmaps are set to the screen 

Q Drawing origin is set to 0,0 

□i Pen width and height are set to 1 

Q Current pattern address Is set to 

Qi All installed fonts are removed and the current selected font is set to 
the system font 

□i Graphics cursor is set to the center of the screen; It is turned off and 
its shape is set to the default shape 

Qi Temporary workspace is initialized (see setjwksp) 
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Set_CUrs_Shape set Current Cursor Shape 

Syntax typedef struct 

{ 

short hot_x; 
short hot_y; 
short width; 
short height; 
short pitch; 
long color; 
short mask_rop; 
short shape_rop; 
PTR data; 
} CURSOR; 

void set_curs_shape (shape) ; 
long shape; 

Type Core 

Description The set_curs_shape function initializes tlie global pointer to the cursor 
shape with the parameter passed to it (which is a pointer in TMS340 
memory). Prior to calling this function, both the cursor shape data and the 
cursor structure must be loaded into TMS340 memory using the 
gsp_malloc and host2gsp functions. The TMS340 memory address of the 
cursor shape data must be assigned to the data element of the cursor 
structure before loading the structure. The TMS340 memory address of the 
cursor structure can then be passed to this routine to select the cursor. A 
default cursor shape (an arrow) is installed with the graphics manager and 
is available until this routine is called to download a user cursor. The default 
cursor shape can be restored by invoking set_curs_shape with a 
parameter of 0. 

In the set_curs_xy function, (x, y) is the position of the top-left pixel of the 
cursor if hot_x and hot_y are zero. These values are subtracted from the 
current cursor position to give the top-left hand corner of the cursor starting 
drawing point. For example, in a simple crosshairs cursor of width 1 6 pixels 
and height 12 pixels, the hot_x is set to width/2, that is, 8; and similarly, 
hot_y is set to 6. If the current cursor position is (320, 240), the rectangle 
defining the cursor is drawn with its top left hand corner at 320 - hot_x and 
240 - hot_y, that is (31 2, 236). This puts the center of the crosshair cursor 
at position (320, 240), the desired cursor position. 

The data that defines the cursor consists of (1) cursor mask data, and (2) 
cursor shape data. This data defining the cursor shape must be contiguous; 
that is, thecursorshapedatamustimmediatelyfollowthe cursor maskdata. 
The pitch of this cursor data is indicated by the pitch element in the 
CURSOR structure. 
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Set Current Cursor Shape set_CUrs_Shape 

Two raster operators, mask_rop and shape_rop, determine how the cursor 
mask data and cursor shape data, respectively, are expanded onto the 
screen. For the masl^ data, the background and foreground colors are al- 
ways and OFFFFFFFFh, respectively. The color of the cursor shape is de- 
termined by the color element in the cursor structure. 

An example of cursor data follows. The mask data consists of an array width 
by height with Os where the cursor is located and 1 s elsewhere. The raster 
op for this data is AND(1). The shape data is an array width by height with 
1 s where the cursor is located and Os elsewhere. The raster op for the shape 
data is 0R(8). Typically, the shape of the cursor in the maskdata is one pixel 
wider than that of the shape data. This enables the cursor outline to be seen 
when placed over a background of the same color as the cursor shape. 

Example masks for a simple crosshair cursor: 



11111111111 

11110001111 
11110001111 
11110001111 
10000000001 
10000100001 
10000000001 
11110001111 
11110001111 
11110001111 

11111111111 



00000000000 n 

00000000000 
00000100000 
00000100000 
00000100000 
00111011100 
00000100000 
00000100000 
00000100000 
00000000000 
00000000000 



1 



MASKDATA 



SHAPEDATA 
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Set_CUrs_Shape Set Current Cursor Shape 
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Example #include <dos.h> 

#include <conio.h> 
#include <typedefs.h> 
#include <tiga.h> 
#include <extend.h> 
#def ine ESC OxlB 

CONFIG config; 



char far 
{ 

0xFF,0x87, 
0XFF,0X01, 
Ox7F, OxCO, 
OxlF, OxFO, 
0x07, OxFC, 
0x01, OxFF, 
OxECOxFF, 
0x00,0x00, 
0x00, Ox7C, 
0x00,0x11, 
0x40,0x04, 
0x10,0x01, 
0x44,0x00, 
OxOE,OxOO, 

}; 



PencilData [ ] = 



0x03, 0x00, OxFF, 
0X03, 0X00, OXFF, 
0x03, 0x00, 0x3F, 
0x03, 0x00, OxOF, 
0x03,0x00,0x03, 
0x03,0x00,0x00, 
0x03, 0x00, OxFO, 
0x00,0x00,0x00, 
0x00,0x00,0x00, 
0x00,0x00,0x80, 
0x00,0x00,0x20, 
0x00,0x00,0x08, 
0x00, 0x00, 0x4E, 
0x00,0x00,0x06, 



0x03,0x03, 
0X00,0X03, 
OxCO, 0x03, 
OxFO, 0x03, 
OxFC, 0x03, 
OxFF, 0x03, 
OxFF, 0x03, 
0x78,0x00, 
0x72,0x00, 
0x10,0x00, 
0x04,0x00, 
0x01,0x00, 
0x00,0x00, 
0x00,0x00, 



0x00, OxFF, 
0X00, OXFF, 
0x00, 0x3F, 
0x00, OxOF, 
0x00,0x03, 
0x00,0x80, 
0x00, 0xF8, 
0x00,0x00, 
0x00,0x00, 
0x00,0x80, 
0x00,0x20, 
0x00,0x88, 
0x00, 0x3E, 
0x00,0x02, 



0x03, 
0X80, 
OxEO, 
0xF8, 
OxFE, 
OxFF, 
OxFF, 
0xF8, 
0x26, 
0x08, 
0x02, 
0x00, 
0x00, 
0x00, 



0x02, 
0X03, 
0x03, 
0x03, 
0x03, 
0x03, 
0x03, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 



0x00, 
0X00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 



OxFF, 0x01, 
0X7F,0X80, 
OxlF, OxEO, 
0x07, 0xF8, 
0x01, OxFE, 
OxCO, OxFF, 
OxFD, OxFF, 
0x00, OxFC, 
0x00,0x39, 
0x40,0x08, 
0x10,0x02, 
0x84,0x00, 
OxlE,OxOO, 
0x00,0x00, 



0x02, 
0X03, 
0x03, 
0x03, 
0x03, 
0x03, 
0x03, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 



0x00, 
0X00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00 



CURSOR far pencil = 

{0x0000, OxOOlB, 0x0011, OxOOlC, 0x0020, OxOFL, 1, 8, OL}; 



struct 

{ 

short x,y; /* coordinates 

short left, right; /* buttons 
short xl,yl, x2,y2; /* boundary 
} mouse; 



*/ 
*/ 
*/ 



union REGS regs; 
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Set Current Cursor Shape set_CUrs_Shape 



/* checks for an installed mouse driver 

check_mouse ( ) 

{ 

regs.x.ax =0; 

int86 (0x33, Sregs, Sregs) ; 

return (regs.x.ax) ; 
} 

]:nouse_driver ( ) 
{ 

/* get mouse coordinates 

regs.x.ax = 11; 

int86 (0x33, Sregs, Sregs) ; 

mouse. X += regs.x.cx; 

mouse. y += regs.x.dx; 

/* ensure the mouse stays within the screen boundary 

if (mouse. X < mouse. xl) 

mouse. X = mouse. xl; 
if (mouse. X > mouse. x2) 

mouse. X = mouse. x2; 
if (mouse. y < mouse. yl) 

mouse. y = mouse. yl; 
if (mouse. y > mouse. y2) 

mouse. y = mouse. y2; 
/* tell the GSP cursor*/ 
set_curs_xy (mouse. X, mouse. y); 
/* get the mouse buttons */ 
regs . x . ax = 3 ; 
int86 (0x33, &regs, Sregs) ; 
mouse. left = regs.h.bl &. 1; 
mouse. right = (regs.h.bl & 2) » 1; 
} 
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set_CUrs_Shape Set Current Cursor Shape 
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install_cursor (type) 

short type; /* 0=default (arrow) , l=user (pencil) */ 

{ 

/* Address of user cursor in GSP mem */ 

static PTR UserCurs = OL; 

if (type) 
{ 

/* User cursor type specified */ 

if ( UserCurs == OL ) 

{ 

/* Execute this block 1st time only */ 

unsigned short num_bytes; 

/* download cursor shape data to GSP */ 

num_bytes=( (pencil. height * pencil. pitch) « 1) » 3; 
pencil .data= (PTR) gsp_malloc (num_bytes) ; 
host2gsp (PencilData, pencil. data, num_bytes, 0); 
/* download cursor structure to GSP */ 

num_bytes=sizeof (CURSOR) ; 
UserCurs= (PTR) gsp_malloc (num_bytes) ; 
host2gsp (Spencil, UserCurs, num_bytes, 0); 
} 

set_curs_shape ( UserCurs ) ; 
} 
else 

set_curs_shape((PTR)0) ; /*Use default if type==0 */ 
} 

main ( ) 

{ 

char key; 

short CursorType=l; 

if (check_mouse ) 
{ 

if (set_videomode(TIGA, INIT | CLR_SCREEN) ) 

{ 

if (install__primitives >= 0) 

{ 

get_config(&config) ; 

print f ("Press . . . \n") ; 

printfC ESC to quit\n"); 

printfC SPACE to toggle cursor shapesXn"); 

printfC LEFT mouse button to draw points\n") ; 

/* assign a new cursor shape */ 

install_cursor (CursorType) ; 
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Set Current Cursor Shape set_CUrs_Shape 



/* initialize mouse to the center of the screen */ 

mouse . x=conf ig .mode . disp_hres»l; 

mouse, y = config.mode.disp_vres»l; 

set_curs_xY (mouse. X, mouse. y); 

/* intialize mouse boundary */ 

mouse. xl = mouse. yl =0; 

mouse. x2 = config.mode.disp_hres - 1; 

mouse. y 2 = config.mode.disp_vres - 1; 

/* turn on cursor */ 

set_curs_state (1) ; 

for(;;) 

{ 

/* move the cursor with the mouse */ 

mouse_driver ; 

/* if left button pressed draw a point */ 

if (mouse. left) 

draw_point (mouse. X, mouse. y); 

if (kbhitO) 

switch ( getchO ) 

{ 

case ' ' : 

install_cursor (CursorType'^=l) ; 
break; 
case ESC : 

set_curs_state(0) ; /* Turn cursor off */ 
set_videomode (PREVIOUS, INIT) ; 
exit(O); 
} 
} 
} 
set_videomode (PREVIOUS, INIT) ; 

} 
} 

else printf ("Mouse driver required for this example\n") ; 

} 
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set_CUrs_State Set Current Cursor State 

Syntax void set_curs_state (enable) 

short enable; 

Type Core 

Description The set_curs_state function displays the cursor (if enable is nonzero) or 
removes it from the screen. 

Example See set_curs_shape. 
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Set Current Cursor Position set_CUrs_xy 

Syntax void set_curs_xy (x, y) 

short x; 
short y; 

Type Core 

Description The set_curs_xy function modifies the pixel coordinates of the cursor's 
hotspot.The cursor coordinates are not relative to the drawing origin; they 
are always relative to the top left hand corner of the screen. 

Example See set_curs_shape. 
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Set_draw_Origin Set Drawing Origin 

Syntax void set_draw_origin (x, y) 

short x; 
short y; 

Type Extended 

Description The set_draw_origin function sets the drawing origin for all subsequent 
drawing functions. All coordinates specified for all drawing functions are rel- 
ative to the drawing origin. 

Example See styledjine. 
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Set Destination Bitmap set_dstbin 



Syntax void set_dstbm(addr, pitch, xext,yext,psize) 

long addr; 
short pitch; 
short xext; 
short yext; 
short psize; 

Type Extended 

Description The set_dstbm function sets the TMS340's destination bitmap for subse- 
quent bitbit or drawing functions, involving the function with an address 
of sets the destination bitmap to the screen. 

The pitch of the destination bitmap must be a multiple of 1 6, Currently, no 
clipping is performed in a linear bitmap; the calling program must do this. 
Future TIGA revisions will provide this capability. 
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set_dStbm set Destination Bitmap 

Example #include <typedefs.h> 
#include <tiga.h> 
#include <extend.h> 
CONFIG config; 



/* function to save portion of screen defined by arguments*/ 
/* into a linear bitmap and return the address */ 

unsigned long save_off screen (width, height, x_left, y_top) 
short width, height, x_left, y_top; 
{ 

unsigned long address; 

address = (PTR) gsp_malloc( ( (long) width * (long) height * 

(long) config. mode. disp_j)size) /8) ; 
if (address) 
{ 

/* turn off transparency, otherwise pixels of color */ 
/* will not be copied into the destination bitmap */ 
transp_off () ; 
set_srcbm(01,0,0,0,0) ; 

set_dstbm (address, width * config. mode. disp_psi2e, 
width, height, config.mode.disp_j)size) ; 
bitblt (width, height, x_left, y_top, 0, 0); 
set_dstbm(01, 0, 0, 0, 0) ; 
} 

return ( addr e s s ) ; 
} 

/* function to restore to the screen a pre-saved */ 

/* rectangular region in heap pointed to by address */ 

restore_onscreen (address, width, height, x_left, y_top) 

unsigned long address; 

short width, height, x_left, y_top; 

{ 

if (address) 
{ 

/* turn off transparency, otherwise pixels of color */ 

/* will not be copied into the destination bitmap */ 

transp_off ; 

set_srcbm (address, width * config. mode. disp_psize, 

width, height, config.mode.disp_psize) ; 

set_dstbm(01,0,0,0,0) ; 

bitblt (width, height, 0, 0, x_left, y_top) ; 

set_srcbm(01, 0, 0, 0, 0) ; 
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Set Destination Bitmap set_dstbm 



mainO 
{ 

short w, h, X, y, i; 

PTR save; 

if (set_videomode(TIGA, INIT | CLR_SCREEN) ) 

{ 

if (install_jprimitives >= 0) 

{ 

get_config{&config) ; 

clear_screen (LIGHT_MAGENTA) ; 

w = config.mode.disp_hres»4; 

h = config.mode.disp_vres»4; 

X = config.mode.disp_hres»2; 

y = config.mode.disp_vres»l; 

/* save a portion of the screen */ 

save = save_off screen (w, h, x, y) ; 

/* clear screen to the current background color */ 

clear_screen (-1) ; 

X = y = 0; 

/* restore saved region to various places on screen */ 

for (i = 0; i < 8; i++) 

{ 

restore_onscreen(save, w, h, x, y) ; 

X += config.mode.disp_hres»3; 

y += config.mode.disp_vres»3; 
} 

gsp_f ree (save) ; 
} 

set_videomode (PREVIOUS, INIT) ; 
} 
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Set_fCOlor set Foreground Color 

Syntax void set_f color (color) 

long color; 

Type Core 

Description The set_f color function sets theCOLORI B-file register to the color index 
replicated by the pixel size of the current configuration. 

Example See fili_polygon. 
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Set Interrupt Handler setjnterrupt 

Syntax void set_interrupt (level, priority, enable, scan_line) 

short level; 
short priority; 
short enable; 
short scan_line; 

Type Core 

Description The setjnterrupt function enables/disables a previously installed interrupt 
service routine. The routine must have been installed via the install_rlm 
function or the combination of create_alm and install_alm. 

The level parameter indicates the Interrupt level where the interrupt rou- 
tine was installed. The priority is returned by the getJsr_prlorities func- 
tion when the interrupt is installed, to distinguish between different interrupt 
service routines on the same interrupt level. If enable Is true (nonzero), the 
interrupt is enabled; othenA^ise, it is disabled. 

The scan_iine parameter is valid only for display interrupts (Interrupt level 
1 0). It is used to set the line at which the interrupt occurs. If the scan_iine 
parameter is -1 , then the value for the scan_iine is taken to be that passed 
in the previous invocation of setjnterrupt. This allows the interrupt to be 
enabled/disabled without re-specifying the scan_iine parameter. 

For more details on extensibility and the use of this function, refer to Chapter 
4. 

Example See Section 4.9. 
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set_palet initialize a Palette 

Syntax typedef struct 

{ 

char r; 

char g; 

char b; 

char i; 
}PALET; 

void set_palet (count, index, palet) 
long count; 
long index; 
PALET far *palet; 

Type Core 

Description The set__palet function loads the palette on the board using the paiet 
array. The number of palette entries to be loaded is passed in argument 
count. Argument index designates where the palette loading is to start. 
This allows for a palette to be loaded one piece at a time, rather than all at 
once. The range that is being loaded is checked by this function to ensure 
that it does not overflow the palette; thus, if the starting index plus the 
number of entries (count) is greater than the palette size, the count value 
Is decreased by the appropriate amount. 

In the PALET structure, r, g, and b refer to the red, green, and blue 
values for the colorentry (0 being off and all 1 s being full on); i is an intensi- 
ty level for monochrome displays. See also Appendix B.7 for details on color 
selection. 

On systems that store the palette data in display memory (such as those us- 
ing theTMS34070), this function reloads every palette data area in the frame 
buffer. Thus, if the system contains multiple display pages, every page is 
loaded by this function. 

Example See similar call to set__palet_entry. 
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Set a Palette Entry set_palet_entry 



Syntax Int set_palet_entry (index, r, g, h, i) 

long index; 
char r; 
char g; 
char b; 
char i; 

Type Core 

Description The set_palet_entry function initializes one entry index in a palette. If the 
function aborts, it returns the value false (zero); otherwise, it completes nor- 
mally and returns true (nonzero). 

In the palette structure, r, g, h refer to the red, green and blue values for 
the color entry (0 being off and all 1s being full on), and i is an intensity 
level for monochrome displays. See also Appendix B.7 for details on color 
selection. 

On systems that store the palette data in display memory (such as those us- 
ing the TMS34070) this function reloads the palette entry in every palette 
data area in the frame buffer. Thus if the system contains multiple display 
pages, every page is loaded by this function. 

Example See get_palet_entry. 
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set_patn Set Current Pattern Address 



Syntax 



Type 



typedef structure 

{ 

ushort width; 
ushort height; 
ushort depth; 
PTR data; 
} PATTERN; 

void set j)atn (p) 
PATTERN far *p; 

Extended 



Description The set_patn function sets the current drawing pattern as specified by the 
PATTERN structure pointed to by p. Currently, only 16x16x1 patterns are 
supported in TIGA's extended graphics primitives. The application mustf irst 
install its pattern data using gsp__malloc to allocate TMS340 storage 
memory and then use host2gsp to transfer them to TMS340 memory. A 
pointer to the desired pattern in TMS340 memory Is then set in the PAT- 
TERN structure before calling set_patn. 

Example See patnfill_piearc. 
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SetPensize set_pensize 

Syntax void set_pensize (w, h) 

short w, h; /* pen width and height */ 

Type Extended 

Description The set_pensize function specifies the width and height of a rectangular 
pen. These dimensions are used for any subsequent drawing operations 
with the pen. 

Example See install_usererror. 
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set_pmask set Plane Mask 

Syntax void set_pmask (mask) 

long pmask; /* plane mask */ 

Type Core 

Description The set_pmask function specifies tiie plane masi< tliat is used In subse- 
quent drawing operations. The mask determines which bits in a pixel can 
be modified during drawing operations. The Os in the mask enable modifica- 
tion of the corresponding bit planes. The Isinthe mask write-protect the cor- 
responding planes. 

The plane mask designates which bits within a pixel are protected against 
writes and affects all operations on pixels. The protected bits are replicated 
for each pixel throughout the 32-bit plane mask. The 1s in the plane mask 
specify protected bits in the destination pixel that cannot be modified, while 
the Os specify bits that can be altered. The plane mask can be read by 
means of a call to the get_pmask function. See the TMS34010 User's 
Guide for a further discussion of plane masking. 
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Set Pixel Processing Operation set_ppop 



Syntax void set_ppop(ppop_code) 

short ppop_code; /* pixel processing operation code */ 

Type Core 

Description The set_ppop function defines the pixel processing operation for subse- 
quent drawing operations. The specified Boolean or arithmetic operation 
determines the manner in which source and destination pixel values are 
combined. The range for the ppop_code argument is to 21 . The codes are 
described in the following table: 

Table 3-2. Pixel Processing Options 



Code 


Replace Destination Pixel with: 


Code 


Replace Destination Pixel with: 





source 


11 


NOT source AND destination 


1 


source AND destination 


12 


all Is 


2 


source AND NOT destination 


13 


NOT source or destination 


3 


alios 


14 


source NAND destination 


4 


source OR NOT destination 


15 


NOT source 


5 


source EQU destination 


16 


source + destination 


6 


NOT destination 


17 


ADDS (source, destination) 


7 


source NOR destination 


18 


destination - source 


8 


source OR destination 


19 


SUBS (destination - source) 


9 


destination 


20 


MAX (source, destination) 


10 


source XOR destination 


21 


MIN (source, destination) 



The TMS34010 User's Guide (literature number SPVU001) describes the 
details of these operations. 

Example See draw line and zoom rect 
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set_srcbm Set GSP's Source Bit Map 

Syntax void set_srcbm(addr/ pitch, xext,yext/psize) 

long addr; 
short pitch; 
short xext; 
short yext; 
short psize; 

Type Extended 

Description The setjsrcbm function sets the TMS340's source bitmap for subsequent 
bitbit functions. Invoking the function with the address of sets the source 
bitmap to the screen. 

The pitch of the source bitmap must be a multiple of 1 6. Currently no clipping 
is performed in a linear bitmap, the calling program must do this. Future 
TIGA revisions will provide this capability. 

Example See set_dstbm. 
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Set Text Rendering Attributes seMextattr 

Syntax int set_textattr(pControl, count/ arg) 

char far *pControl; 
short count; 
short far *arg; 

Type Extended 

Description The seMextattr function sets text rendering attributes, pcont roi Is a con- 
trol string specifying the attributes to be set. Values associated with attrib- 
utes can be specified either as immediate values in the control string, or as 
arguments passed In the array arg. The number of attributes in the control 
string must be passed In parameter count . 

When a values Is passed as a string literal, It should be placed between the 
% character and the attribute. For example, to assign the value 1 to attribute 
a enter: 

set_textattr("%la'S 1, 0) ; 

To pass the same value as an argument, an asterisk Is placed between the 
% character and attribute, and the value 1 1s provided as the first argument 
(element 0) In the passed array: 

short arg [ 1 ] ; 
arg[0] = 1; 
set_textattr("%*a", 1, arg[0]); 

The number of attributes successfully set is returned. This is the current list 
of valid attributes: 

Attribute Description Option Value 

%a alignment = top left, 1= baseline 

%e additional Intercharacter spacing 1 6 bit signed integer 
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seMimeoUt Set Timeout Delay Value 

Syntax void set_timeout (value) 

short value; /* value in milliseconds */ 

Type Core 

Description The set_timeout function sets the value of the timeout value (in millisec- 
onds) that determines how long the host waits for a TMS340 function to 
complete prior to calling the error function with a timeout. The user can ig- 
nore timeouts altogether by installing a user error handler function that is 
called when the timeout occurs. This function can be made to ignore such 
timeouts. 

Example See install usererror. 
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Set Transparency Mode set_transp 



Syntax void set_transp(mode) 

short mode; 

Type Core 

Description The set_transp function, if implemented (on TI\/IS34020 systems only), 
changes the transparency mode. Currently, these are the modes supported 
are: 

mode = Transparency on source equals zero 

mode = 1 Transparency on source equals COLORO 

mode = 2 Transparency on result equals zero 

mode = 3 Transparency on result equals COLORO 

On TMS3401 systems, only mode 2 Is supported. 
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set_vector Set Contents of GSP Trap Vector 

Syntax unsigned long set_vector (trapnum, newaddr) 

unsigned short trapnum; 
unsigned long newaddr; 

Type Core 

Description The set_vector function writes the specified 32-bit address contained in 
newaddr into the trap vector specified by trapnum. The address originally 
in this trap is returned. This function should be used whenever it is neces- 
sary to modify a trap vector address. 
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Set Emulation Mode set videomode 
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Syntax int set_videomode (mode, style) 

short mode; 
short style; 

Type Core 

Description The set_videomode function sets up the video mode to be used. Every 
TIG A application should start with a call to this function with a mode of TIG A 
and the initialize flag set (non-zero) prior to invoking any other TIGA func- 
tion. This function sets up the mode to be used in a particular application. 
These are the valid modes: 



TIGA 


EGA 


MDA 


VGA 


HERCULES 


AI_8514 


CGA 


PREVIOUS 



All TIGA applications should call set_videomode with tiga mode upon 
starting. They should then call set_videomode again at the end of their pro- 
gram to restore IBM emulation (since in most cases the board on which 
TIGA is being run is the primary video board). The mode selected could be 
PREVIOUS which restores the emulation mode from a global. However, if a 
particular application wants to switch back and forth between several 
modes, it is recommended that a call be made to get_videomode and the 
mode be saved bytheapplication.The saved mode can be used to terminate 
the TIGA application and to restore the board to the initial state. 

If a call is made to set_videomode and that particular video mode is not 
supported by the board, the routine returns false (zero). 

The style parameter is used to determine the manner in which the mode 
is set up in on entry. This list describes valid styles: 



NO INIT 



INIT GLOBALS 



INIT 



Used during an application to switch between TIGA and 
other emulation modes. It enters TIGA, leaving all global 
variables intact. 

initializes the global variables only, by calling 
set_config with the init_draw flag true and by restoring 
the timeout value and the user error handler. The heap 
pool is retained, which keeps the downloadable exten- 
sions installed. 

Initializes global variables and dynamic memory (heap 
pool).This frees all allocated pointers and thus deletes 
all downloaded extensions. 
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set Videomode Set Emulation Mode 



The style parameter contains one further option, which can be selected by 
ORing with the above style parameter: 

CLRjSCREEN This parameter should be used at initialization when you 
are using the INIT_GLOBALS or INIT styles. The screen 
is blanked while the video registers are initialized. 
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Set Windowing Mode set_windOWing 



Syntax void set_windowing (enable) 

short enable; 



Type Core 

Description The set_windowing function sets the two-bit windowing code contained in 
the CONTROL I/O register. The windowing codes are 

Qi 00 - No windowing 

m 01 - Interrupt request on write in window. 

□i 1 - Interrupt request on write outside window. 

^^ 11 - Clip to window. 

For a more detatiled description of the windowing operation, refer to the 
TMS34010 User's Guide {WteraXure number SPVU001). Care must be taken 
in using this function. The extended drawing primitives assume windowing 
option 3 (clip to window) is set. Setting the interrupt request modes (1 and 
2) should only be done after downloading an interrupt service routine for the 
window violation interrupts (see Installing Interrupts in Chapter 4). 
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set_wksp Seta Temporary Workspace 



Syntax void set_wk.sp (addr, pitch) 

unsigned long addr; /* starting address */ 

unsigned long pitch; /* workspace pitch */ 

Type Core 

Description The set_wksp function sets the workspace environment variables to the 
specified address and pitch. The workspace memory is used by functions 
such as f ill_polygon to draw a 1 -bit-per-pixel image of the polygon before 
expanding it to the screen. 

The area used for the workspace may be allocated from offscreen memory 
(a description of which is returned by the get_offscreen_memory function) 
or from from heap using gsp_malloc. It must be large enough to hold a 
1 -bit-per-pixel representation of the current screen coordinates with a pow- 
er of 2 pitch. 

Example See fiil_polygon. 
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Draw styled Line Stytedjine 



Syntax 



void styled_line(xl, yl, x2, y2, style, mode) 



short xl, yl; 
short x2, y2; 
long style; 
short mode 



/* start coordinates 

/* end coordinates 

/* 32-bit line style pattern 

/* selects 1 of 4 drawing modes 



*/ 
*/ 
*/ 
*/ 



Type 



Extended 



Description The styledjine function uses Bresenham's algorithm to draw a styled line 
from point (xi, yi) to point (x2, y2). The line is a single pixel thick and is 
drawn in the specified line-style pattern. 

Q Arguments xi and yi specify the starting coordinates. 

Q Arguments x2 and y2 specify the ending coordinates. 

Qi The last two arguments, style and mode, specify the line style and 
drawing mode. 

Argument style is a long Integer containing a 32-bit repeating line-style pat- 
tern. Pattern bits are used in the order 0,1 31 , where is the rightmost 

bit (the LSB). The pattern is repeated modulo 32 as the line is drawn. A bit 
value of 1 in the pattern specifies that the foreground color is used to draw 
the corresponding pixel. A value of in one of the line style pattern bits 
means that the corresponding pixel is either drawn in background color 
(modes 1 and 3) or not drawn (modes and 2). Four drawing modes are 
supported: 

mode Do not draw background pixels (leave gaps), and do 

load new line-style pattern from style argument. 

mode 1 Draw background pixels in COLORO, and load new lin- 

style pattern from style argument. 

mode 2 Do not draw background pixels (leave gaps), and do re- 

use old line-style pattern (ignore style argument). 

mode 3 Draw background pixels in COLORO and re-use old line- 

style pattern (ignore style argument). 

The current style pattern used by the styledjine function is available by 
calling the getjenv function. See the get_env function description for more 
Information. 
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Styledjine Draw styled Line 



Example #include <typedefs.h> 
#include <tiga.h> 
#include <extend.h> 

CONFIG config; 

main ( ) 
{ 

long xl, yl, x2, y2, i, mask; 

if (set_videomode(TIGA, INIT I CLR_SCREEN) ) 
{ 

if (install_primitives >= 0) 
{ 

get_config(&config) ; 

/* draw spiral using styled line segments 

set_draw_origin ( config . mode . disp_hres»l , 

config.mode.disp_vres»l) ; 

x2 = 0; 

y2 = -20 « 16; 

/* line style pattern 

mask = 0x93E493E4; 

styled_line (0, 0, 0, 0, mask, 0); 

for (i = 1500; i > 0; — i) 

{ 

xl = x2; 
yl = y2; 
x2 += yl » 4; 
y2 -= xl » 4; 

styled_line(xl»16, yl»16, x2»16, y2»16, 
-1,2); 
} 
} 

set_videomode (PREVIOUS, INIT) ; 
} 
} 
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Swap Source and Destination Bitmaps SWap_bm 

insieissmmisisssm 

Syntax void swap_bm{) 

Type Extended 

Description The swap_bm function swaps the pointers to the structures containing 
the source and destination bitmaps. This is useful for copying bitmap data 
offscreen, then at some later point, swapping the bitmaps and restoring 
the data back onscreen. 

Example See zoom_rect. 
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synchronize Synchronize Host and GSP Communications 
Syntax void synchronize O 

Type Gore 

Description The synchronize function ensures that the TMS340 completes all pending 
operations before it returns. TIGA supports two-processor execution and 
some conditions require them to be synchronized. For instance, if the host 
downloads data that is being manipulated by the TMS340, it is essential that 
the TMS340 finishes with it before the host ovenwrites the data. 

Example See install usererror. 
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Render an ASCII String text_OUt 



•^KS^KWsjjsffSfflwasssssssssffirawsKssssMsssssi^^sww 



>iStSSSS!!)tSfSiSif!SSfi»fSSitifSlilfXiSSli 



Syntax int text_out (x, Y, pString) 

short X, y; 
unsigned char far *pString; 

Type Core 

Description The text_out function renders the ASCI I string pointed to by pst ring in the 
currently selected font using the current set of text drawing attributes. The 
string is a null terminated sequence of 8-bit ASCII character codes. 

The starting position of the string is specified by arguments, x and y. Coor- 
dinate X is the position at the left edge of the string, and coordinate y is the 
position at either the top of the string, or the baseline, depending on the text 
alignment attribute set by a call to set_textattr. 

The return value is the x coordinate of the next character position to the right 
of the string. If the string lies entirely above or below the clipping rectangle, 
the unmodified starting x coordinate is returned. 
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text_Width Return Width of an ASCII String 



Syntax int text_width (pString) 

unsigned char far *pString; 

Type Extended 

Description The text_wlclth returns the width of the string in pixels, as if it were rendered 
using the current selected font and the current set of text drawing attributes. 
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Transparency Off transp_Off 

Syntax void transp_off () 

Type Core 

Description The transp_off function disables transparency for subsequent drawing op- 
erations. Tiie transparency mode set by default is mode 2, transparency on 
result equals zero (see seMransp function) That is, if the pixel operation 
involving source and destination pixels is 0, the destination pixel is not al- 
tered. This can be modified for TMS34020 systems by using the seMransp 
function. 

Example See set dstbm. 



3-181 



transp_on Transparency On 
Syntax void transp_on() 

Type Core 

Description The transp_on function enables transparency for subsequent drawing op- 
erations. The transparency mode set by default Is mode 2, transparency on 
result equals zero (see seMransp function) .That is, if the pixel operation 
involving source and destination pixels is 0, the destination pixel is not al- 
tered. This can be modified for TMS34020 systems by using the seMransp 
function. 

Example See call to transp_off in set_dstbm. 
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Wait for Scan Line wait SCan 
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Syntax void wait_scan( line) 

short line; /* wait until this scan line is reached */ 

Type Core 

Description The walt_scan function waits for a scan line on tlie CRT to be refreshed. 
This function does not return control to the calling routine until the specified 
line is scanned by the electron beam. Control is returned at the start of the 
horizontal blanking interval that follows the designated line. Scan lines are 
numbered in ascending order, starting with line at the top of the screen. 
Only visible scan lines are counted. 

This function can be used to synchronize drawing operations to the electron 
beam of a CRT display. For example, when drawing an animated sequence 
of frames, transitions from one frame to the next appear smoother if an area 
of the screen is not redrawn at the same time it is output to the CRT. 

If argument line is less than 0, the function uses the value in place of the 
argument value. If argument line is greater than the bottom scan line, the 
function uses the number of the bottom scan line in place of the argument 
value. 
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Z00m_rect zoom Rectangle 
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Syntax 



void zoom_rect (ws/ hs, xs, ys, wd, hd, xd, yd, linebuf) 



short ws, hs; 
short xs, ' ys; 
short wd, hd 
short xd, yd; 
short linebuf; 



/* 
/* 
/* 
/* 



source width and height 
source top left corner 
destination width and height 
destination top left corner 



/* scan line buffer 



*/ 
*/ 
*/ 
*/ 
*/ 



Type 



Extended 



Description The zoom_rect function expands or shrinks a source rectangle on the 
screen or a linear bitmap to fit the dimensions of a destination rectangle on 
the screen. Horizontal zooming is accomplished by replicating or deleting 
rows of pixels. This type of function Is sometimes referred to as a stretch blit. 

The first four arguments define the source rectangle: 

Q The width ws 

[^ The height hs 

Q The coordinates of the top left corner (xs, ys) 

ws and hs must be non-negative. 

The next four arguments define the destination rectangle: 

Oi Width wd 

Q Height hd 

Q Coordinates of the top left corner of the rectangle (xd, yd) 

wd and hd must be non-negative. 

The final argument, linebuf, is a buffer large enough to contain one com- 
plete line of the display. The function uses the buffer as temporary working 
storage; The minimum buffer size (in bits) is the number of pixels per line 
times the number of bits per pixel. This buffer is a pointer to TMS340 
memory and therefore must be allocated (by calling for example gsp_mal- 
loc) before invoking the function. 

The zoom_rect function can be made to zoom from a linear bitmap by set- 
ting the source bitmap global using the set_srcbm function. This function 
only works if the pixel size of the source bitmap is the same as the screen. 
Thus, if the desired effect is to perform a zoom_rect on binary data, this 
must be done in two stages. First download the binary bitmap and use bitbit 
to expand this to the current pixel size to a linear bitmap. Then perform a 
zoom__rect on this linear bitmap onto the screen. 
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Zoom Rectangle Z00m_rect 



Example finclude <typedefs.h> 
#include <tiga.h> 
#include <extend.h> 

CONFIG config; 

short far arrow_shape [ ] = 

{ 

0x0003, 0x0007, OxOOOF, OxOOlF, 0x003F, 0x007F, OxOOFF, 
OxOlFF, OxOSFF, OxOlFF, 0x007F, 0x00F7, OxOOF2, OxOlEO, 
OxOlEO, OxOOCO 

}; 

#define ARROW_W 16 
#define ARROW_H 16 

main ( ) 
{ 

int i; 

PTR arrow_addr_bin, arrow_addr_col, buffer; 

long arrow_size; 

if (set_videomode(TIGA, INIT | CLR_S GREEN ) ) 

{ 

if (install_j)rimitives >= 0) 
{ 

get_config(&config) ; 

/* set up linear bitmap with binary data for arrow */ 

arrow_size = ARROW_W * ARROW_H; 

arrow_addr_bin = gsp_malloc ( (arrow_size+7) /8) ; 

/* transfer shape data from host to gsp */ 

host2gsp (arrow_shape/ arrow_addr_bin, 

(arrow_size+7) /8, 0) ; 
/* set up a color bitmap for the arrow shape */ 
arrow_size *= config. mode. disp_j3size; 
arrow_addr_col = gsp_malloc ( (arrow_size+7) /8) ; 
/* set the source bitmap to the binary arrow shape */ 
set_srcbm(arrow_addr_bin, ARROW_W, ARROW_W, 

ARR0W_H,1); 
/* set destination bitmap to the color arrow shape */ 
set_dstbm(arrow_addr_col, ARROW_W * 

config. mode. disp_psize, ARROW_W, ARROW_H, 
config. mode. disp_psize) ; 
/* blit binary arrow and expand it to color arrow */ 
set_colors (LIGHT_CYAN, LIGHT_BLUE) ; 
bitblt (ARROW_W, ARROW_H, 0, 0, 0, 0) ; 
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/* set the source bitmap to the color arrow */ 

swap_bm ( ) ; 

/* set the destination bitmap to the screen */ 

set_dstbm(01, 0, 0, 0, 0) ; 

/* set pixel processing to max as the results are */ 

/* normally better */ 

set_ppop(20) ; 

/* set up zoom-rect buffer to hold 1 scan-line */ 

buffer = gsp_malloc (config.mode.disp_hres * 
config.mode.disp_j5size) ; 

/* now zoom-rect the arrow to the screen */ 

zoom_rect (ARROW_W, ARROW_H, 0, 0, ARR0W_W«2, 
ARROW_H, 0, 0/ buffer) ; 
} 
set videomode (PREVIOUS, INIT) ; 
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Chapter 4 

Extensibility Through the 

User Library 
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Extensibility was a prime consideration in the design of tlie TIGA-340 Inter- 
face. TIGA-340 is extensible through the addition or manipulation of its user 
library, which is a collection of C-callable routines compiled or assembled 
with the TMS340 software toolset. 

Graphics standards prior to TIGA have limited the software developer by 
providing a fixed set of graphics drawing primitives. In the rapidly changing 
graphics market, a fixed set of primitives is unacceptable. During the devel- 
opment of the TIGA graphics interface, incorporating extensibility into the 
standard was a major design goal. The result was the linking loader de- 
scribed In this chapter, which, along with a collection of routines, can be 
used by an application or device driver to install custom-made graphics 
primitives. 
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Dynamic Load Module 

4.1 Dynamic Load Module 

The key to TIGA's extensibility is tiie Dynamic Load Module (DLM). This 
module Is a collection of C or assembly routines written by the application 
or device driver programmer, and linked together to form the module. The 
DLM is downloaded at run time into TMS340 memory and integrated with 
the TIGA graphics manager. Once downloaded, each routine contained 
within the module is callable using the same conventions as the TIGA core 
or extended primitives. 

TIGA currently supports two types of dynamic load modules: 

Qi Relocatable load module (RLM), and 

Qi Absolute load module (ALM). 

The routines which compose a dynamic load module can be either stan- 
dard C-type functions callable from either the host processor or from the 
TMS340, or interrupt service routines called on reception of an interrupt via 
the TIGA standard interrupt handler. 

4.1.1 Relocatable Load Modules 

Relocatable Load Modules (RLMs) are produced directly using the TMS340 
compiler and assembly tools and are in common object file format, oxCOFF. 
A description of this file format is given in the TMS3401 Assembly Lan- 
guage Tools User Guide. These modules contain the necessary relocation 
entries so that they can be loaded anywhere in TMS340 memory. They may 
also contain unresolved references to TIGA core or extended primitives, 
which are resolved when they are loaded. Furthermore, they contain all the 
necessary symbol information stored after loading a symbol table file so that 
subsequent RLMs that are loaded may reference the functions in another 
RLM. The installation of an RLM is performed by invoking the lnstall_rlm 
function which. In turn, invokes tigalnk, the linking loader. 

4.1.2 Absolute Load Modules 

Absolute Load Modules (ALMs) are created from relocatable load modules 
by calling the create_alm function. This function in turn calls the linking 
loader to link and save (instead of link and load) the resultant TMS340 
memory image, tigalnk uses the TIGA heap management routines to allo- 
cate a space in TMS340 memory where the ALM will be loaded, tigalnk 
then links and relocates the module to the area starting address in heap. 
Thus, the ALM can only be loaded into this one area in memory. The heap 
area for the module is then freed by the create_alm routine. It is therefore 
imperative that the state of the heap in TMS340 memory Is the same when 
the ALM is created as when it is installed. Normally, this can be achieved 
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by always initializing heap prior to calling create_alm and then reinitializing 
heap when the module is installed. Heap initialization can be performed by 
calling set_videomode with an init style. 

The reason for incorporating ALMs into TIGA is that installation of RLMs 
requires the application or device driver written for TIGA to call the 
install_rlm function, which in turn invokes the linking loader. This requires 
about 70 — 1 0OK bytes of free main host memory, depending on the symbol 
table size of the module being installed. For many applications this is the 
most direct and flexible method for installation of functions, as the module 
can be relocated and the symbols accessed by subsequent module loads. 
However, for certain applications and application drivers, not enough 
memory is available to use this method. An example of this is the AutoCAD 
driver, ADI. By the time AutoCAD calls the ADI, all available PC memory 
has been appropriated, leaving no room for install_rlm to invoke the linking 
loader. Using the ALM, no memory is required. The instali_alm function 
contains only a short piece of code to load the module into TIGA, since no 
external linking or relocation needs to be made. The create_alm function 
can be called when ADI is installed (at boot time). Because this is prior to 
AutoCAD being invoked, the PC memory is free to invoke tigalnk to create 
the ALM file. 

When loading an ALM, heap is allocated to store the module. The start ad- 
dress is compared to the one returned when the module was created. If they 
are the same ,the ALM is loaded into TIGA; if not, the load is aborted. A 
further restriction with ALMs is, since the symbol information is also no long- 
er available within the file (as it is with RLMs), that modules loaded subse- 
quently cannot reference functions in an ALM. 
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4.2 Generating a Dynamic Load l\/lodule 

A TIGA dynamic load module consists of the following three parts: 

I^ A collection of C and/or assembly routines, some (or all) of which are 
to become TIGA extensions or interrupt service routines. 

Q TIG AEXT section declaration. Required only if TIGA extensions are be- 
ing declared. 

□i TIGAISR section declaration. Required only if TIGA interrupt service 
routines are being declared. 

This document does not describe the mechanics of generating the TMS340 
source and object code of a user function. This is discussed fully in the 
TMS34010 C Compiler Reference Guide and the TMS34010 Assembly 
Language Tools User's Guide. If the user library is to contain functions writ- 
ten using TMS3401 assembly code then certain guidelines need to be met 
to ensure that the C environment is maintained by the assembly language 
function. For a description of how to interface assembly language routines 
with the C environment, see Section 5.4 of the TMS34010 C Compiler Ref- 
erence Guide. 

Dependent on whether or not a DLM contains extensions or interrupt ser- 
vices routines, one or two specially named COFF sections must be created 
and linked with the module. If the module contains extensions, the a section 
called TIGAEXT must be created. If the module contains interrupt service 
routines, then a section called TIGAISR must be created. The format of 
these sections is described below. 

4.2.1 TIGAEXT Section 

The TIGAEXT must contain one and only one address reference for each 
extension contained within the module (that is callable from the host). For 
example, if the module contains two functions called my_funci and 
my_f unc2 the section declared would look like this: 



TIGAEXT - This COFF section contains references for all 
extensions contained in the module it is linked with. 



External References 

.globl _iny_funcl, _my_func2 
/Start section declaration 
.sect ".TIGAEXT" 

.long _iny_funcl /command number within module 
.long _my_func2 /command number 1 within module 
.text /end section 
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4.2.2 The TIGAISR Section 



The TIGAISR section contains two entries for every interrupt service routine 
contained within the module. These entries specify an address reference 
to the ISR and the interrupt number of the ISR. 

For example, if two ISRs called my_inti and my_intio were contained 
within the module, then the section declared would look like this: 



'•TIGAISR - 


- This COFF section contains information for all ; 


; of the 


ISRs contained in the module it is linked with. ; 


/External 


References 


.globl 


my intl, my intlO 


/Start section declaration 


.sect 


".TIGAISR" 


.long 


_my_intl 


.long 


1 /interrupt number 1/ 


.long 


_my_intlO 


.long 


10 /interrupt number 10; 


.text 


/end section 



Note that the TIG AEXT and TIGAISR sections must contain the exact num- 
ber of declarations for the external functions to be installed. This is because 
TiGALNK uses the length of these sections to determine the number of decla- 
rations. 

4.2.3 Linking the Code and Special Sections into an RLM 

Once the user functions have been written, they are compiled and/or as- 
sembled, producing a series of COFF object files ( . ob j). These files should 
be partially linked together with the object files generated by assembling 
the TIGAEXT and/or TIGAISR sections. Below is an example where two 
functions and two interrupt service routines are created and linked into a 
RLM. 

The source files contain the following: 

myf uncs FunctlonS my_f unci and my_f unc2 

t igaext . asm References for the above (as in the example) 

myint s . asm TwO interrupt routines, my_intl, and my_int 10 

tigaisr .asm References and Trap numbers for the above ISRs 
Step1 : Assemble and/or compile all of the source files: 

cc myfuncs tigaext myints tigaisr |)^ 

This produces four object files: 

myf uncs. obj 
t igaext. obj 
myints. obj 
tigaisr. obj 
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Step 2: Partially link all the object modules together to form the RLM: 

gsplnk -o EXAMPLE. RLM -r - cr myfuncs.obj tigaext.obj 
myints.obj tigaisr.obj Q 



The result of the linking is a relocatable load module entitled example . rlm. 

I I 

Note: 

In some versions of the linker, the warning: -Unresolved Reference to 
"_cjnit00". is displayed. It can be ignored. 

' I 
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4.3 Installing a Dynamic Load Module 



To invoke the commands installed in a dynamic load module, it must first be 
installed into the TIGA graphics manager. The module file is in the form of 
a file in a directory of the host PC. If this directory is not the current working 
directory, the TIGA environment variable must first be set up to point to this 
directory, tigalnk uses the environment variable to find the DLM. The ac- 
tual installation procedure differs from RLM to ALM. 

4.3.1 Installing a Relocatable Load Module 

A relocatable load module is installed by the lnstall_rim function. Below 
is an example program written in Microsoft C which explains how to install 
the example described in the previous section, example . rlm. 

Example 4^1. 

#include <tiga.]i> 

main ( ) 
{ 

short module; 

/* initialize TIGA */ 

if (!set_videomode(TIGA, INIT) ) 

{ 

print f ("Fatal Error - TIGA not installed\n") ; 

exit(O); 
} 

/* attempt to install module */ 
if ((module = install_rlm ( "EXAMPLE" ) ) < ) 
{ 

printf ("Fatal Error - couldn't install Example RLM\n") ; 
printf ("Error code = %d\n", module); 

exit(O); 
} 
/* code to invoke the module functions */ 

set videomode (PREVIOUS, INIT); 



The lnstali_rlm function is invoked with the filename of the RLM file. Either 
a full pathname can be given, or just the final part of the filename, when ei- 
ther the current directory is used or that directory set by the TIGA environ- 
ment variable. A default extension of . rlm is assumed unless one is given. 
The install_rlm function will return either the module id for the RLM, which 
will be used when the functions are invoked, or an error code if some error 
occurred. Error codes are negative values, module identifiers are always 
positive (including zero). 
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4.3.2 Installing an Absolute Load Module 

An absolute load module must first be created from a relocatable load mod- 
ule. Below Is an example program written in Microsoft C that explains how 
to create an ALM from the example described in the previous section. 

Example 4^2. 

#include <tiga.h> 

main ( ) 
{ 

register return_code; 

if (!set_vicieomode(TIGA, INIT) ) 
{ 

printf ("Fatal Error, TIGA interface not installed. \n") ; 

exit (1) ; 
} 

/* attempt to create the module */ 
return_code = create_alm( "EXAMPLE", "EXAMPLE"); 
if (return_code < 0) 
{ 

printf ("Fatal Error in creation of 'aim' file\n"); 
printf ("Error code = %d\n", return_code) ; 

exit(l); 
} 
/* further initialization code */ 

set videomode (PREVIOUS, INIT) ; 
} 

init_driver 
{ 

register return_code; 

if ( ! set_videomode (TIGA, INIT) ) 
{ 

printf ("Fatal Error, TIGA interface not 
installed. \n" ) ; 

return (0); 
} 

/* attempt to install the module */ 

return_code = install_alm ( "EXAMPLE" ) ; 
if (return_code < 0) 

{ 

printf ("Fatal Error in installation of 'aim' file\n") ; 

printf ("Error code = %d\n", return_code) ; 

return (0) ; 
} 
/* code to invoke the module functions */ 

set videomode (PREVIOUS, INIT) ; 
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The example assumes that at the time the program is run Initially, tigalnk 
can be invoked by create_alm to produce the ALM file. The invocation pro- 
duces an EXAMPLE. ALM file in the same directory as example .rlm. Default 
extensions of .rlm and .alm are assumed unless overridden by the file 
names supplied. create_alm produces an ALM file only if it does not al- 
ready exist. This generally saves the program the unnecessary time of rec- 
reating the ALM every time the program is run. If the application requires 
to create a new ALM, it must first delete the old one explicitly. 

The example also assumes that the part of the program that uses the user 
extensions in the ALM is performed after invoking the init_driver function. 
This scenario is typical with application drivers. The main program actually 
does very little more than initialization and calling the DOS TSR exit func- 
tion. Later, the application calls an init_driver type function to get the driver 
ready for subsequent application calls. At this time the TIGA environment 
is re-initialized and the ALM is installed. install_alm does not invoke 
tigalnk but uses a trivial loader to move code from the host PC file into 
TMS340 memory. 
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4.4 Invoking Functions in a Dynamic Load l\/lodu[e 

The process of invoking a function in a DLM is done in two parts. The first 
part involves the selection of the function, which is described in this section. 
The second part is the actual invocation of the function and the passing of 
its parameters from the host to the TMS340. That part Is described In subse- 
quent sections. 

4.4.1 Command Number Format 

User extensions that are installed In a DLM are identified by a unique com- 
mand number. This command number consists of a 1 6-bit word split into the 
following fields, as Figure 4-1 shows: 



Figure 4^1. Command Number Format 
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1 ) The function type (Bits 1 A — 1 5) : 

00 = direct-mode 

01 = C-packet 

10 = reserved for future use 

11 = reserved for future use 

2) The module number (between and 31 ) (Bits 9 — 13): 

31 for TIGA core primitives. 

30 for TIGA extended primitives installed via the install__primitives 

function. 
thru 29 for user modules in the order of installation. 

3) The function number within the module (Bits — 8). 

The function type field currently selects between the C-packet mode and di- 
rect-mode functions. These two modes determine the manner in which the 
parameters of the function are passed between the host and the TMS340. 
The two modes will be described in subsequent sections. 

The module number is a unique identifier for each module. TIGA supports 
up to 32 DLMs, numbered from to 31 . The TIGA core primitives are always 
installed at initialization time as module number 31 . Likewise, the DLM that 
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contains the TIGA extended primitives is always assigned module number 
30 by the install_primitivesfunction. The remaining 30 module slots, num- 
bered 0—29, are assigned to user DLMs as they are installed. The first user 
DLM installed is assigned the number 0, the second the number 1 , and so 
on. 

The function number specifies one of the 51 2 possible functions that can be 
contained within a module. Function numbers are defined by the order that 
they are declared in the TIGAEXT section within a module. For the example, 
described in Section 4.3 my_f unci would be designated function number 
0, and my_f unc2 would be designated function number 1 . 

4.4.2 Using Macros in Command Number Definitions 

The definition of the command number may be subject to change in future 
versions of TIGA. To minimize the potential changes to an application, mac- 
ros are provided in the tiga . h include files to enable the command number 
of a function to be specified without referencing the individual bits in the 
command number. These are the macros: 

CORE_CP (function_nuinber) 
CORE_DM (function_nuitiber) 
EXT_CP (function_nuniber) 
EXT_DM (f unction_nuinber) 
USER_CP (module | function_nuinber) 
USER_DM (module j function_number) 

coRE_cp and core_dm select C-packet or direct-mode functions with a module 
number of 31 (for the TIGA core primitives). Similarly, ext_cp and ext_dm se- 
lect C-packet or direct-mode functions with a module number of 30 (for the 
TIGA extended primitives). user_cp and user_dm are used for user exten- 
sions. They take a single argument, which is the module number returned 
by the install_rlm or [nstaii_alm function ORed with the function number 
of the function from its position in theTIGAEXTsection. The module number 
should be passed as it is supplied from the install procedure. 

These macros should always be used when specifying command numbers. 
If they are not, and an application hard-codes the bits in a command number, 
there is a risk of incompatibility with future versions of TIGA. 
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4.4.3 Passing Parameters to the TIGA Function 

The invocation of a TIGA function can be done in two ways, depending on 
the type of function call that Is made. These are C-packet or direct-mode 
calls. 

C-packet functions are the easiest of the two to write and have a more flex- 
ible parameter format. C-packet functions receive their parameters on the 
stack; thus it is very easy to develop a function that becomes a user exten- 
sion by first writing it and debugging it on the host side. The function can then 
be extracted from the host code and be recompiled under the TMS340 C 
compiler. Any parameters it received on the host side will be passed from 
host to TMS340 via a TIGA communication driver routine and then pushed 
onto the TMS340 C stack so that the function behaves just as if it were in- 
voked local to the host. To do this, however, extra data must be sent along 
to the TMS340 describing the type and size of each parameter. 

The extra overhead of sending this data, plus the time taken to format the 
parameters and push them onto the stack can be eliminated by using di- 
rect-mode. This just sends raw data into the communication buffer used for 
host to TMS340 communication. The user extension function receives on 
the stack a single parameter that is a pointer to the communication buffer 
where the data is stored. The function itself must pick up the data from this 
buffer in the expected format. 

Most applications will be developed using C-packet initially. Those functions 
that are more time critical would be modified to use direct-mode. The 
changes to the source code of an extension to change it from C-packet to 
direct-mode are not that significant as will be seen from examples given lat- 
er. The following sections give a complete description of C-packet and direct 
modes. 
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4.5 C-Packet Mode 

To invoke a User extension using C-packet mode, three pieces of informa- 
tion need to be supplied: 

□i Tiie type of call the function uses 

i^ The function's command number 

Qi Description of the function arguments 

4.5.1 The Type of Call 

The current C-packet system supports three basic types of function calls: 

cp_cmd This entry point is for functions that do not require any form 
of return data. 

cp_ret This entry point is for functions that require only a single stan- 

dard C type return value. 

cp_a!t This entry point is for those functions which pass pointers to 

data that is modified indirectly by the function called. 

draw_a_line(xl, yl, x2, y2) WOUld USe Cp_Cmcl 

poly_line(10, &point_list) WOUld USe Cp_Cmd 

i = read_point (x, y) WOUld USO Cp_ret 

copy_mem( &src, &dst, len) WOUld USe Cp_alt 

An additional set of entry points is used when the argument list has the po- 
tential of being too large for the size of the communication buffer used to 
transfer parameters between the host and the TMS340. These entry points, 
cp_cmd_a, cp_ret_a, and cp_alt_a, have the same functionality as those 
described above, with the added capability of allocating additional space for 
large amounts of arguments data, at a cost of speed performance. These 
entry points should be avoided when the user knows that the argument 
length of the function in question will not exceed the maximum size dictated 
by the communication buffer's data size (which is a field of the CONFIG 
structure returned by get_config). 

4.5.2 The Command Number 

Section 4.4.1 on page 4-1 describes in detail the command number format. 
The command number should always be specified in the form: 

USER_CP (module | function_number) 

for user C-packet extensions, where module Is the module ID of the DLM 
returned at install time and f unction_number is the position of the function 
in the TIGAEXT section. 
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4.5.3 Description of Function Arguments 

To call the desired function, each of that function's arguments must be un- 
derstood by the graphics manager, so data can be passed to the DLM func- 
tion in the expected form. Each individual argument is called a packet and 
has its own separate header. Entering the packet headers is made easier 
by the use of additional defines in the tiga. h include file to represent the 
different data types. Below is a list of the currently supported data types: 

_woRD (a) Immediate WORD argument a 

_swoRD (a) Immediate signed WORD argument a 

_DW0RD (a) Immediate Double WORD argument a 

_BYTE_PTR (b, a) BYTE array ptr a with b elements 

_woRD_PTR (b, a ) WORD array ptr a with b elements 

_DwoRD_PTR (b, a) DWORD array ptr a with b elements 

_STRING (a) Null-terminated string ptr a 

_ALTBYTE_PTR (b, a) Functlon altered BYTE array pointer 

_ALTwoRD_PTR (b, a) Functlon altered WORD array pointer 

_ALTDW0RD_PTR (b, a) Function altered DWORD array pointer 

Because the immediate arguments passed in Microsoft C are always pro- 
moted to short type, there is no BYTE identifier. If immediate char values 
are passed, either the_woRD or_swoRD identifier should be used. Also, since 
immediate short types are the only datatypes that need be promoted (to 32 
bits) by the graphics manager, they are the only data size to have a signed 
identifier. All other arguments' sign extension requirements should be han- 
dled by the called routines. 

4.5.4 C-Pacl(et Examples 

The exact argument list of the C-packet entry points is as follows: 

entry_point_name(CMD_ID, num_j)ackets, packetl, ... , packetn) 

where: 

cni_number conimand number 

npackets number of C type packets 

packetl. . .packetn Packet data (see below) 

Below are some examples of user extensions. These examples are not 
supplied Tl-extended primitives. 
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Example function: 

init_graf ix ( ) 

Qi The function requires no return data. (Use cp_cmd) 
Qi Tlie function's command number was stored in cmd_id . 
Q The function has no arguments. 

Resulting include file entry: 

fdefine init_graf ix ( ) cp_cmd(USER_CP (CMD_ID) , 0) 

Example function: 

f ill_rect (w, h, x, y) 

Qi The function requires no return data. (Use cp_cmd.) 
I^ The function's command number was stored in cmd_id . 
i^ The function has 4 arguments, all words . 

Resulting include file entry: 

fdefine fill_rect (w,h,x,y) \ 

cp_cmd(USER_CP (CMD_ID) , 4,_W0RD (w) ,_WORD (h) ,_WORD (x) ,_WORD (y) ) 

Example function: 

poly_line(n, &linelist) 

Q The function requires no return data (Use cp_cmd.) 

Q The function's command number was stored in cmd_id . 

Qi The function has 2 arguments, word, n and word_ptr, iine_iist . 

Resulting include file entry: 

fdefine poly_line (n,ptr) \ 

cp_cmd(USER_CP (CMD_ID) ,2,_W0RD (n) ,_W0RD_PTR(2*n,ptr) ) 
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Example function: 

init_inatrix (&matrix) 

Q The function Initializes the array pointed to by &matrix indirectly. (Use 

cp_alt) 
□i The function's command number was stored In cmd_id . 
Q The function has 1 argument which points to a 4 x 4 element function 

altered array of longs. 

Resulting Include file entry: 

#define initjmatrix (ptr) \ 

cp_alt (USER_CP ( CMD_ID ),1, _ALTDWORD_PTR ( 1 6 , pt r ) ) 

4.5.5 Overflow of the Command Buffer 

When a command of any kind (primitive or user function) is invoked by an 
application, the communication driverfunctions transfer its parameters from 
host memory Into a temporary buffer in the TMS340 memory (called a com- 
mand buffer). If one of the parameters of the function Is a pointer, then the 
pointer itself Is not copied over, only the data that is being pointed to is co- 
pled. If the pointer Is an array, as in the polyline function, then it can be of 
arbitrary length. Thus, It is very simple for the application to overflow this 
fixed length buffer by, for example, asking TIGA to draw a million element 
polyline. The application must know the size of data that It Is attempting to 
transfer Into the TMS340 processor memory and check that it will fit in the 
command buffer. For this reason, the command buffer size is included as 
an element In the configuration structure returned by get_config. Note that 
if a C-packet entry point is being used, allowances must be made for the 
packet type and size words, which also use space in the command buffer. 

Memory space management is required for all direct-mode and three regu- 
lar C-packet entry points. However, the application can use the _a C-packet 
entry points (for example, cp_cmd_a) which check the size of the parame- 
ters and download them In the normal way If they fit. If they do not fit, the 
entry points attempt to allocate a temporary buffer from the heap pool to 
store the parameters. If the allocation Is not successful the error function is 
invoked. The checking of the parameter size requires two passes through 
the arguments and thus some speed overhead Is Incurred using this tech- 
nique. However, a rapid real-time function does not commonly use arrays 
too large to fit In the command buffer. 
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Another technique provided in TIGAforthe management of large amounts 
of data, which may overflow the command buffer, is the direct-mode entry 
points dm_poly and dmjpoly. These entry points turn the buffer into a cir- 
cular queue so that any size of data can download into the buffer. This tech- 
nique requires the writing of a custom TMS340 processor command that 
manages the data and the handshaking employed. 



4-17 



Direct Mode 



4.6 Direct Mode 

The principal difference between C-packet and direct modes is tiiat in direct 
mode.wiien tiie downloaded function is invoked on the TMS340 side, the 
arguments are not on the stack as in C-packet mode. The downloaded func- 
tion is invoked with a single argument, which is a pointer to a data area 
where the host downloaded the parameters. The function itself must fetch 
them from this data area into the local variables.This process makes the 
writing of functions slightly more complicated, but this is offset by the in- 
crease in performance. These functions are intended to improve the per- 
formance of invoking TIGA extensions from TMS340. They are not meant 
(although they could be used) for functions that are called from other down- 
loaded functions from the TMS340 side. Such functions that need to be 
called from both the host and TMS340 (by another downloaded function) 
are best written in C-packet or should have an alternate C-callable entry 
point. 

Note that for the fastest possible transfer of data the direct mode entry 
points do not check the size of the data being transferred. The application 
has to ensure that the data being transferred does not overflow the com- 
mand buffer. 

A further difference between C-packet and direct mode was that in C-packet 
mode the arguments passed to a function could be of any combination of 
immediate data and pointers in any particular order. This is not the case with 
direct-mode. No packet information is sent with the data, specifying whether 
it is immediate or not, and its size. It is the direct-mode entry point itself that 
determines what format the parameters can be specified in, and, in turn, 
how these parameters are received in the TMS340 communication buffer. 
In the following sections is a list of the direct-mode entry points and the para- 
meterization of their arguments. 

4.6.1 Standard Command Entry Point 

void dm_cmd(cmd_nuitiber, length, argl, . .,argn) ; 
short cind_nuiaber; 
short length; 
short argl...argn; 

This command is the most commonly used for direct-mode commands in 
the TIGA system. It has a single length argument and an arbitrary-length 
list of immediate value arguments; it has no return value. The length speci- 
fied is the number of 1 6-bit words that are sent; thus to send a long, length 
should increase by 2. 
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The TIGA core function poke_breg uses this entry point, it sends a 1 6-bit 
register number and a 32-bit value to be ioaded into the register. Note that 
the length is three, since threel 6-bit words are pushed onto the stack (2 of 
them being the MSW and LSW of value). 

tdefine poke_breg (regno, value) \ 

dm_cmd(POKE_BREG, 3, (short) (regno), (long) (value)) 

The data in the communication buffer looks as follows: 
Figure 4^2. Data Structure of dm_cmd 

16-bit words 



data.ptr ► regno 



value (LSW) 



value (MSW) 



The poke_breg function has one parameter on the stack, which is 
data_ptr. The function contains the following TI\/IS340 assembly code to 
extract the data from the communication buffer: 



cim_poke 


breg: 




move 


A0,*-SP,1 


; save AO 

; (Field Size 1 is 32-bit s by default) 


move 


*-A14,A8,l 


; get data_j)tr 


setf 


16,1,0 


; set Field Size to 1 6-bit s 


move 


*A8+,A0,0 


; get regno into AO 


move 


*A8,A8,1 


; get value into A8 
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4.6.2 Standard Command Entry Point with Return 

unsigned long dm_ret (cmd_nuinber, length, argl, — , argn) ; 
short cmd__nuinber; 
short length; 
short argl... argn; 

This command is similar to din_cmd described in Section 4.6.1 on page 
4-1 8. The difference is that after calling the TMS340 function, the host waits 
for the command to finish, and then fetches and returns the standard C re- 
turn value. The value is returned as a long, but is of the same type as that 
returned by the called routine (signed or unsigned, etc.). The value is re- 
turned in the DX:AX registers. As with dm_cmd, dm_ret specifies length 
in 16-bit words. 

The TIGA core primitive get_nearest_color uses this entry point. It sends 
4 bytes of red, green, blue, and intensity (which are all promoted to shorts 
by the C-compiler), returning a long index into the palette. 

dm_ret (GET_NEAREST_COLOR, 4, (short) (r), (short) (g) \ 

(short) (b) , (short) (i) ) 
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4.6.3 Standard Memory Send Command Entry Point 

void dm_psnd(cmd_number, length, ptr) 
short cmd_nuinber; 
short length; 
char far *ptr; 

This command is used to call functions that require Information In the form 
of an array or structure. Note that in this case the length specified is In bytes, 
not 1 6-bit words as In the previous two entry points. The ptr argument Is 
a far pointer Into host memory. The contents of this pointer are down loaded 
Into the communication buffer. 

The TIGA extended primitive draw_polyline uses this entry point. Notice 
that the numpts Is multiplied by 4 since every point consists of two coordi- 
nates (x and y), each of which is 2 bytes long. 



#def ine draw_polyline (numpt s , pts ) 

dm_psnd(DRAW_POLYLINE, (short) (4*(numpts) ) , 
(short far *) (pts) ) 

The data in the communication buffer looks as follows: 
Figure 4-3. Data Structure of dm_j)snd 



data^ptr 



16-bit words 



numpts X 4 



ptslOLx 



ptslOI.y 



ptsIILx 



pt8(1).y 



X coordinate of first point 

y coordinate of first point 

X coordinate of second point 

y coordinate of second point 
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Because the entry point always sends the byte count Into the first word of 
the communication buffer, the TMS340 function itself must scale it to a 
point-count by dividing the value by 4. The primitive contains the following 
TMS340 assembly code to extract the data from the communication buffer: 

_dm_draw_j)olyline : 



move 
setf 
move 



srl 



*-A14,All,l 

16,1,0 

*A11+,A10,0 



2,A10 



get data_j)tr 

set field Size to 16-bits 

1st word is number of bytes 

the post-increment of All means that 

it is now a pointer to pts[0] 

convert to numpts 
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4.6.4 Standard Memory Return Command Entry Point 

unsigned long dm_jDget (cmd_number, length, ptr) 
short cmd_number; 
short length; 
char far *ptr; 

This command is used to call functions that return information in the form 
of an array or structure. The length (in BYTES) is sent as the first element 
in the command buffer and invokes the TMS340 function. The function 
writes the return data into the communication buffer at the word following 
the length. 

The TIGA core primitive get_palet uses this entry point. Notice that the 
nument parameter is multiplied by 4 since each palet entry consists of a red, 
green, blue, and intensity byte. 

#define get_palet (nument, pal) \ 

dmjpget (GET_PALET, (short) (4* (nument) ) , (char far *) (pal)) 

The data in the communication buffer contains the one word of data before 
the function is invoked: 

Figure 4-4. Data Structure Before Invoking 6m jigeX 

16-blt words 
data_ptr 



nument « 4 



Following the invocation of the buffer the communication buffer contains: 
Figure 4-5. Data Structure After Involdng dmjpQeX 



16-bit word 



data_ptr- 



nument « 4 


paKOI.g 


pallOLr 


pallOLi : 


pallOLb 







red and green values of first entry 
blue and intensity of first entry 
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4.6.5 Standard String Entry Point 

void din_jpstr (cmd_nuniber, ptr) 
short cmd_nuitLber; 

char far *ptr; 

This command is similar to dmjjsnd, but instead of sending a pointer with 
a known length, it sends a null-terminated string. In this case, the communi- 
cation buffer has no length entry as the first word. Successive bytes of the 
buffer contain the characters in ptr with a null (zero) terminator. 

An example for this entry point can be found in the communication entry 
points tests in the TIGA release (in directory tigapgms\tests\coms), 

4.6.6 Altered Memory Return Command Entry Point 

unsigned long dm_palt (cmd_nuitiber, length, ptr) 
short cmd_number; 
short length; 
char far *ptr; 

This command is used to send and return information in the form of an array 
or structure. This entry point combines the functionality of the dmj3snd 
and dm_pget entry points to send the contents of a pointer (of length by- 
tes), which is then modified by the TMS340 function. When it completes the 
data is returned back into the host memory pointed to by ptr. 

An example for this entry point can be found in the communication entry 
points tests in the TIGA release (in directory tigapgms\tests\coms). 

4.6.7 Send/Return l\/lemory Command Entry Point 

unsigned long dm_ptrx(cmd_nuniber, send_length, send_ptr, 
return_length, return_ptr) 
short cmd_number; 
short send_length; 
char far *send_j3tr; 
short return_length; 
char far *return_ptr; 

This command is used to send information in an array or structure and return 
information to adifferent array or structure. It is similar to dm_palt in Section 
4.6.6 except that data is returned to a different area of host memory. 

An example for this entry point can be found in the communication entry 
points tests in the TIGA release (in directory tigapgms\tests\coms). 
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void din_pcmd(cmd_nuitiber, num_words, wordl, word2,..., 
num_ptrs, cntl, ptrl, cnt2, ptr2, ...) 
short cmd_nuitiber; /* coinmand_nuinber 

short num_words; /* number of words to send 

short wordl; /* immediate data 

short word2; 

/* number of pointers to send 
/* number of bytes in pointer 1 
/* pointer data 



short 


num_ptrs; 


short 


cntl; 


char far 


*ptrl; 


short 


cnt2; 


char far 


*ptr2; 



*/ 
*/ 
*/ 



*/ 
*/ 
*/ 



This command combines immediate and pointer data. The first parameter 
after the command number is the number of words (num_words) to send in 
the same manner as dm_cmd. Following that are the words themselves 
on the stack. After the immediate data is a count of the number of pointers 
to send (num_ptrs). Each pointer is preceded by a count of the number of 
bytes contained in the array or structure that the pointer is pointing to. 

An example for this entry point can be found in the communication entry 
points tests in the TIGA release (in directory tigapgms\tests\coms). 

4.6.9 Mixed Immediate and Pointer Command Entry Point witli Return 



unsigned long dm_j)ret (cmd_number, num_words, wordl, word,.., 
num_j5trs, cntl, ptrl, cnt2, ptr2, ..) 

/* command_number */ 

/* number of words to send */ 
/* immediate data */ 



/* number of pointers to send */ 
/* number of bytes in pointer 1 */ 
/* pointer data */ 



short 


cmd_numbers; 


short 


num_words; 


short 


wordl; 


short 


word2; 


short 


num_ptrs; 


short 


cntl; 


char far 


*ptrl; 


short 


cnt2; 


char far 


*ptr2; 



The command dm_pret is similar to dm_pcmd except that it returns a stan- 
dard C value in the DX:AX registers. 

An example for this entry point can be found in the communication entry 
points tests in the TIGA release (in directory tigapgms\tests\coms). 
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4.6.10 Poly Function Command 



void dm_j)oly(cmd_number, packet_number, packet_size, packet_ptr) 
short cmd_nuirLber; 
short packet_number; 
short packet_size; 
char far *packet_ptr 

This entry point is different from every otiier C-pacl<et and direct-mode entry 
point in tiiat it does not simply transfer data from host to TMS340 memory 
and invoke a command. This command is used for operations that require 
a large amount of data to be transferred and when a certain degree of par- 
allelism is possible; that is, some of the data being sent can be processed 
while the rest is being sent down. For example, the ADI redrawfunction used 
by the TIGA AutoCAD driver uses this entry point to draw some vectors 
while others are being sent by the host. 

The command buffer used by the communication driver to download the pa- 
rameters is turned into a circular queue of packets. The command buffer 
contains the following: 



Figure 4-6. Data Structure of dm_poly 

data_ptf — 



16-bit words 



total number of packets 



number of packets in a burst 



packets sent 



packets used 



start of packet 1 



This entry point sends a burst of packets down from the host to the TMS340. 
It updates the packets-sent count and monitors the packets-used count to 
ensure that there is enough room to download more packets. The user func- 
tion must be specially written to comprehend this handshaking scheme and 
be responsible for the update of the packets used entry. 
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Example 4-3. 



TIGA - Graphics Manager function 



Usage: Example GSP shell routine with dmjpoly entry point. 

Include GSP register definitions 

. copy gspregs . inc 
Include macros 

•mlib gspmac.lib 
Declare globals 

.globl _example_dmpoly 
External References; Arguments Received from Host 



aTOTAL . set 

aPAGE . set 

aSENT . set 

aUSED . set 

aDATA . set 

Rarg 

Recurrent 

Rctotal 

Rctemp 

Rcpage 

Rdata 

BURST_SIZE 

_example_dmpoly : 
mmtm 
Pope 
move 
move 
clr 

page_loop : 

move 
addi 
Push 

burst_loop : 
movk 
sub 
jrge 
add 
clr 

f ull_burst : 
add 

check_loop : 
move 
sub 
jrlt 





lOh 
20h 
30h 
4 Oh 
.set 
.set 
.set 
.set 
.set 
.set 
.set 



AO 
Al 
A2 
A3 
A4 
A5 
16 



/•total number of packets 

/packets per page 

/•packets sent 

/•packets used 

;data starts here; Register usage 

/pointer to arguments 

; count (current) 

; count (total packets) 

; count (temp) 

; count (total per page) 

/pointer to data 



SP,A0,A1,A2,A3,A4,A5,A6,A7,A9 
Rarg ;get pointer to args 

*Rarg (aTOTAL) /Rctotal, ;get total packets 
*Rarg (aP AGE) /Rcpage, ;get packets per page 



Recurrent 

Rarg, Rdata 
aDATA, Rdata 
Rcpage 

BURST_S I ZE , Rctemp 
Rctemp , Rctotal 
full_burst 
Rctotal , Rctemp 
Rctotal 

Rctemp, Recurrent 

*Rarg(aSENT),A8/0 
Recurrent , A8 
cheek_loop 



; clear current count 



/Rctemp is number pkts 



/current count up to date 

/Get count ready 

/Sub off desired count 

/If not ready, then wait 
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packet_loop : 

Grab some data and do something with it 



move *Rdata+,A6,l 
move *Rdata+, A7 , 1 
move *Rdat a+ , A9 , 



dsjs 


Rctemp, packet loop 


move 


Recurrent, *Rarg (aUSED) , 


move 


Rctotal, Rctotal 


3rz 


exit 


subk 


BURST SIZE,Rcpage 


jrgt 


burst loop 


Pop 


Rcpage 


3 rue 


page loop 


Pop 


Rcpage 


mmfm 


SP,A0,A1,A2,A3,A4,A5,A6,A7,A9 


rets 


2 



exit: 



4.6.11 Immediate and Poly Data Entry Point 

void din_ipoly (cmd._nuinber, nShorts, sData,..., ItemSz, 
nitems, pData) 
unsigned short cmd_nuinber; /* command number */ 

unsigned short nShorts; /* Number of immediate short 

words to send */ 

unsigned short sData; /* First short word of data 

to send */ 

unsigned short ItemSz; /* Size of items that follow 

(in bytes) */ 

unsigned short nitems; /* # of items that follow */ 
char far *pData; /* Pointer to data to send */ 

This entry point is similar to dm_poly; it is used for operations tlnat require 
a large amount of data items to be transferred, and the TMS340 has the abil- 
ity to operate on 1 or more data items at a time. Some of the data can be 
processed by the TMS340 while more is being sent down. 

A user function located on the TMS340, which expects data sent by this 
entry point, must be coded using a specific set of rules. When the TMS340 
function is called, it will receive a data pointer in TMS340 memory. The data 
at that address will consist of the immediate data values. The poly data that 
is sent in bursts by the host requires special processing and communication 
protocol inorderto be received. In order to isolate this from the userfunction, 
a service routine is provided called srvjpoly. This service routine should 
be called, once the user function is ready to process the poly data. The pa- 
rameters for this function are as follows: 

srv_ipoly (pItemSrv, pDataBuf ) 

void (*pItemSrv) (); /* Ptr to item handler */ 

char *pDataBuf; /* Address after last iramed. word */ 

The pDataBuf argument is the address immediately following the last im- 
mediate word received by the user function. 
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The pitemsrv Is the address of a function that can, In turn, be called by 
srvjpoly to handle 1 or more Items. This function will be called repetitively 
by srvjpoly until all the items have been received by the host and serviced. 
This function will be called with the following arguments: 



(*pItemSrv) ( nitems, pitems); 

unsigned short nitems; /* Number of items this time 
char *pltems; /* Pointer to data 



*/ 
*/ 



The nitems argument is the number of items requiring service. The pitems 
argument is the address of a data buffer containing nitems worth of data. 

The following is an example of how this entry point can be used. For this ex- 
ample, a polypixel command is Implemented. The function has 2 immediate 
arguments, the foregound color of the pixel, and the raster op to be used to 
draw the pixels. The remaining poly data is an array of points where pixels 
are to be drawn. 

The host program to call the entry point would look like this: 

dm_ipoly (CMD/ 2, color, rop, 4, nPoints, pData) 

where: 

Command number of the polypixel function. 

Specifies that two immediate arguments follow: color and rop. 

First immediate argument. 

Second immediate value. 



CMD 

2 

color 

rop 

4 



nPoints 
pData 



Each item is a point, which in this case is two words. The first 
specifies the X coordinate, the second specifies the Y. The size 
of the item is therefore 4 bytes. 

Specifies the number. 

Pointer in host memory where the point resides. 
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The downloaded TMS340 user function called polypixel looks like this: 



TIGA - POLYPIXEL - Example User function 



Example of a downloaded GSP function which uses the 
dm_ipoly host entry point. 



Include GSP register definitions 

.copy gspregs.inc 
; Include macros 

.mlib gspmac.lib 
; Declare globals 

.globl _PolyPixel 
; External References 

.globl _srv_ipoly 
; Polypixel argument definition 
aCOLOR . set 
aROP .set lOh 
aDATA .set 20h ; address passed to srv_ipoly 



_PolyPixel: 

mmtm SP,A0,A1,A2 

setf 16,0,0 

move @ CONTROL , A2 , 

Pope AO 

move *A0 (aCOLOR) , Al, 

move Al , COLORl 

move * AO ( aROP ) , Al , 

setf 5,0,0 

move Al , @CONTROL+10 , 

setf 16,0,0 
; Ready for poly data, push the address following the 
; immediate data and the address of the service routine 

Push STK 



;save CONTROL register 
;get pointer to data 
;get color 

;set gsp foreground color 
;get raster op 

;use it to set gsp pp op 



A0,A8 

aDATA, A8 
Pushc A8 

movi drawpixels,A8 
Pushc A8 

srv ipoly 



move 
addi 



calla 



;push data address 

;push item service routine 



; All done, cleanup and exit 

move A2,@CONTROL,0 /restore CONTROL register 
mmfm SP,A0,A1,A2 
rets 2 
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Item service routine: drawpixels 

This function is called repetitively by the srv_ipoly 
function until all the items sent by the host have been 
received and serviced. This function is called with two 
stack parameters, the 1st parameter is the number of 
items requiring service, and the 2nd argument is the 
address of the data items in 340 memory. 



drawpixels: 


mmtm 


SP,B10,B11,B12,B13 


move 


STK,B13 


move 


*-B13,B10,l 


move 


*-B13,Bll,l 


move 


B13,STK 


drawloop 


: 


addk 


1,C0L0R1 


move 


*B11+,B12,1 


pixt 


C0L0R1,*B12.XY 


dsjs 


BIO, drawloop 


mmfm 


SP,B10,B11,B12,B13 


rets 


2 



;save registers 

; pop number of items 
;pop ptr to item data 



;get Y:X pixel coords 
;draw a pixel 

;loop until items exhausted 
/restore registers 
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4.7 Downloaded Function 

Userextended routines and interrupt service routines contained inadynam- 
ic load module have the ability to access functions or globals which were 
previously installed into TIGA. This includes the core primitives and the Tl 
extended primitives (provided that they have been installed by the applica- 
tion). Note that certain primitives are host-only primitives and cannot be 
invoked by a dynamically loaded routine. These are 

create.alm host2gsp 

create_esym host2gspxy 

field.extract install_alm 

fieldjnsert install_primitives 

flush_esym instalLrIm 

flush_extended install_usererror 

getJsr_priorities set_config 

get_modeinfo setjimeout 

get_videomode set_videomode 

gsp2host synchronize 
gsp2hostxy 

The downloaded function, whether written in TMS340-C or assembly lan- 
guage, can take advantage of all the facilities of the graphics manager, spe- 
cifically it can 

1 ) Invoke nearly all the TMS340 primitive functions as if they were written 
on the host side. Thus, it can invoke the function setjsalet with the 
parameters used in Microsoft C. Not all the primitives can be invoked 
from the TMS340 side since some require access to host side data 
structures, such as those concerned with the linking loader. Two in- 
clude files containing the graphics manager core functions and ex- 
tended functions (gsptiga.h and gspextnd.h) are supplied for this pur- 
pose. This capability has the advantage that an application can be writ- 
ten and debugged on the host side using Microsoft debug tools and 
then individual functions can be downloaded onto the TMS340 side with 
no changes. 

2) Access global variables of the graphics manager, such as those speci- 
fying display coordinates, directly without invoking functions to do it. An 
include file containing the graphics manager global variables 
(gspgiobs . h) is supplied for this purpose. The file is shown in the fig- 
ure below, which details the global variables that the downloaded exten- 
sion is free to access in the current version of TIGA. 
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extern long bottom_of_stack; /* declared in link file */ 

extern CONFIG config; /* current configuration */ 

extern PALET DEFAULT_PALET [16] ; /* default palette */ 

extern CURSOR DefaultCursor; /* default cursor struct */ 

extern long end_of_drain; /* declared in link file */ 

extern ENVIRONMENT env; /* environment variables */ 

extern ENVCURS envcurs; /* cursor environment */ 

extern ENVTEXT envtext; /* text environment */ 

extern MODEINFO *modeinfo; /* operating mode info */ 

extern MONITORINFO *monitorinfo; /* monitor timing info */ 

extern MODULE Module [32]; /* function module descr. */ 

extern OFFSCREEN_AREA *offscreen; /* pointer to current data */ 

extern PAGE *page; /* pointer to current data */ 

extern PALET palet[]; /* current palette in use */ 

extern PATTERN pattern; /* current pattern info. */ 

extern char *setup; /* current setup pointer */ 

extern short sin_tbl[]; /* sine look-up table */ 

extern long stack_size; /* declared in link file */ 

extern long start_of_dram; /* declared in link file */ 

extern FONT sysfont; /* system font */ 

extern PACKET *sys_free; /* pointer to free packets */ 

extern long *sys_memory; /* pointer to heap packets */ 

Where these variables reference a specific type of declaration, such as 
PALET, the include file gsptypes .h should also be included to define this type 
of declaration. 

4.7.1 Register Usage Conventions 

Assembly language functions used in conjunction with the TIGA primitives 
should follow certain guidelines for register use. The following registers 
must be restored to their original states (the state before the function was 
called) before control is returned to the calling routine: 

□i Status register fields FE1 and FS1 must be restored. Fields FEO and 
FSO need not be restored. 

Q All A-f ile registers except A8 must be restored. A1 4 should not be used 
as a temporary variable by a user function. It must always contain a 
pointer into the C parameter stack, because an interrupt service routine 
(ISR) may interrupt a user function, and that ISR may call a C function 
using the C stack. 

Qi In general, all B-file registers must be restored. However, certain B-file 
registers may be altered by attribute control functions that update pa- 
rameters such as COLORO and C0L0R1. 

Q In general, I/O registers CONTROL, DPYCTL, CONVDP, and INTENB 
should be restored before returning to the calling routine. However, 
some I/O register bits may be altered by attribute control functions that 
update parameters such as the plane mask, pixel processing operation, 
or transparency flag. These register bits typically are not changed by 
graphics output functions. 
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Upon entry to a downloaded extension, certain registers are in a l^nown 
state and contain well-defined parameters. These assumptions cannot be 
made of interrupt service routines, since they can interrupt a function that 
may be using one of these registers for a different purpose. Extensions, 
however, can assume that the following registers are in these states: 

□i Status register: 

■ FE1 = 

■ FS1 = 32 

■ FEO and FSO are undefined 

1^ A-File Registers: STK - A1 4 points to the C-parameter stack. 

Ql B-file registers: 

DPTCH Screen pitch (difference in starting memory addresses of 
any two successive scan lines in display memory). 

OFFSET Memory address of pixel at top left of screen. 

WSTART Top left corner of current window. 

WEND Bottom right corner of current window. 

COLORO Source background color. 

C0L0R1 Source foreground color. 

Q I/O registers: 

CONTROL Contains current pixel processing operation code and 
transparency control bit. These are set by the application 
program and may vary from one call to the next. In con- 
trast, in the window mode, PBH and PBV bits are set to 
specific values. The window mode is set to enable clip- 
ping without interrupts (W = 3). The PBH and PBV bits are 
both zero. 

CONVDP Is set up for the screen pitch. 

PMASK Contains the current plane mask. 
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4.7.2 TiGA Graphics Manager System Parameters 

The TIGA graphics manager assumes that certain system parameters are 
under its control. Dynamic load modules should not alter the following regis- 
ters: 

1^ The master interrupt enable bit (IE) in the status register. 
Q The cache disable bit (CD) in the CONTROL register. 
Q The DRAM refresh control bits (RR and RM) in the CONTROL register. 
Q The four host interface registers (HSTADRL, HSTADRH, HSTDATA, 
and HSTCTL). 
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4.8 Example Programs 



The TIGAPGMS directory that is shipped with TIGA contains several exam- 
ple functions. To gain the maximum benefit from the following sections of 
this guide, they should be read in conjunction with a hard copy of the listings 
of the source code of those examples. 



4.8.1 Stars Example 



The TIGA release disk with the example programs contains a stars directory 
that is an example of the use of C-packet and direct-mode extensions of 
TIGA. This demonstration program may be familiar because it has been 
ported to many different graphics environments. It basically consists of mov- 
ing through a three-dimensional galaxy in which stars grow larger as they 
are approached and then disappear off the edge of the screen. As they do 
so, new stars are created in the distance. This scenario is performed in four 
ways. First, using host calls to TIGA extended primitives to perform the 
drawing of the stars. Second.where the host calls to a custom TMS340 C 
routine using the C-packet communication mechanism. Third, where the 
host calls a custom direct-mode C routine. Finally, where the direct-mode 
routine has been re-written using TMS340 assembly code. The stars pro- 
gram prints out the elapsed time to call these different functions, and the 
time saving is evident. It should be noted at the outset that this example, 
though demonstrating the capabilities of downloading TIGA extensions, is 
very artificial. The time savings in a real application is typically better than 
with this example, especially when the downloaded function performs 
something a little more substantial than drawing a few pixel-wide stars. 

This example consists of the following source files: 

stars . c Main program (Microsoft-C) 

star.h Insert file containing type definitions and external refer- 

ences 

data.c Star shapes 

starscp.c C-packet extension to draw a Star (TMS340-C) 

starsdm. c Direct-mode extension to draw a star (TMS340-C) 

starsasm. asm Dlrect-mode extension to draw a star (TMS340-assembly) 

starsgsp.asm TIGAEXTfile describing extension routine names 
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The routine that forms the downloaded extension Is one that draws a single 
star. The four versions of it are 

draw_star_host In file stars. c 

draw_star_cp In file starscp.c 

draw_star_dm In file starsdm. c 

draw_star_asra in file star sasm. asm 

A comparison between the draw_star_host and draw_star_cp shows that 
besides the function name, the two are identical (apart also from the more 
important fact that one is compiled In Microsoft C and the other In TMS340 
C). This underlines an important advantage of TIGA: that it is possible to 
take an existing application running under Microsoft C, move a function to 
the TMS340 side, and invoke it with the same parameterization as if it were 
locally resident and obtain an Immediate speed improvement, as can be 
seen from running this program. Furtherspeed improvement can be accom- 
plished with just a little more work. 

A comparison between the draw_star_cp and draw_star_dm functions 
shows that after the first four lines of the direct-mode version, the functions 
are again identical. The only difference between them highlights the funda- 
mental difference between C-packet and direct-mode functions. Direct- 
mode functions receive parameters, just as the host downloads them, as 
sequential items in a communication buffer. The direct-mode function re- 
ceives a single parameter, which is a pointer to the data area of the commu- 
nication buffer where the data has to be fetched. In the C-packet case, the 
functions parameters are sent down in packets describing the size and type 
of the data being sent. Then a C-packet interpreter parses these packets 
and pushes parameters onto the stack where the C-packet extension ex- 
pects to find them. This enables the C-packet routine to be called just as if 
It were local to the host program, but it incurs the additional time overhead 
of sending more information in the packet than the data itself.The di- 
rect-mode extension eliminates this overhead but puts a very slight extra 
burden on the extension to fetch its own data. Because the transition from 
C-packet to direct mode is very simple, it Is expected that most applications 
will use C-packet to start and then move to direct mode for those time-critical 
functions that need to be optimized. 

The final function draw_star_asm also uses direct mode, but the function 
no longer uses the TIGA bitbit function to draw the star. Instead, it re-codes 
the whole function in TMS340 assembly language. This function requires 
the most effort form the application programmer to produce. Not every ex- 
tension should use this approach, but there is a well-defined route that al- 
lows an easy progression from host alone, through the simpler approaches 
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of C-packet and direct mode, to the custom assembly function. The custom 
assembly function allows a programmer to develop applications quickly, op- 
timizing time-critical functions to the limit. 

4.8. 1. 1 Generating the Downloadable Extension File 

The extension consists of the files containing the three downloaded subrou- 
tines, a data file containing the star shapes, and a special file containing the 
TIGAEXT section (starsgsp). The latter declares the list of downloaded 
functions to be installed in a specific order so that they can be referenced 
later. The order in which the functions appear in the TIGAEXT section define 
the command numbers used when the functions get invoked thus: 
draw_star_cp has a command number of 0, draw_star_dm has a com- 
mand number of 1 , and draw_star_asm has a command number of 2. All 
thesef lies are linked together using the TMS340 linker (in the make file) with 
the -cr and -r options.This produces the relocatable load module 
starsgsp . rim. Note that In building the rim file the linker produces the mes- 
sage » warning: entry point symbol _c_intOO undefined. This can be 
ignored. 

4.8. 1.2 Installing the Downloadable Extension File 

The initialization routine of stars . c performs the installation of the rim file 
by calling install_r[m. If the call to install_rlm returns a negative result, an 
error occured; if it returns a positive number or zero, it is the module number 
of the installed group of functions. Every installed RLM receives its own 
module id. The first id is 0, the second id is1 , etc. Because this application 
was invoked with set_videomode style of init, which initializes the heap, 
and as a by-product of this, deletes all extended primitives that were in- 
stalled, the application can be assured that the id of the first set of installed 
extensions is 0. Thus, the module identifier (mod_star) can be a constant 
in the program. 

The expected approach for the common mode of operation is that an appli- 
cation flushes out all extended primitives and downloads a single RLM file 
containing all its extensions. This approach has some minor speed improve- 
ments over the more general approach where the module number is not 
known until runtime and the command number needs to be stored in a vari- 
able. 

Note that no directory Is specified in the filename of the downloadable ex- 
tension. This is not a problem for a development environment because the 
current directory is the one searched first and the one where the extension 
is stored. In a production mode where different TIGA applications and driv- 
ers are stored in different directories, the user should set up a TIGA library 
directory that is pointed to by the -i field of the TIGA environment variable. 
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4.8. 1.3 Invoking the Downloadable Extensions 



The three update_cp, _din and _asm functions are the ones that actually 
need to invoke the extensions. The extensions are invoked through the use 
of TIGA communication entry points; cp_cmd for the C-packet call and 
cim_cmd for the two direct-mode calls. To make the invocations more read- 
able, these calls are #defined to function calls that look like regular host 
functions. 

All the communication entry points take as a first parameter the command 
number of the TMS340 function to be invoked. The entry point consists of 
a function command number indicating the order In which the function ap- 
pears in the TIGAEXT section, ORed with the module number (which from 
the previous section is known to be and so can be ignored). Following that 
are the commands parameters: 

1) C-Packet The number of packets, 4, followed by 4 word packets 
with parameters of the actual parameter data. The word macros build 
a packet containing the data size and type for the C-packet handler to 
interpret. 

2) Direct Mode The number of 1 6-bit words, 4, followed by four 1 6-bit 
words pushed onto the stack. 
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4.8.2 Curves Example Program 

The curves example program draws a series of graphs of mathematical 
functions. It is similar to the stars example described above. The major dif- 
ference is that it installs the extensions as separate modules. Thus, rather 
than assuming the module Id is 0, the module id that is returned from the 
3 calls to install_rlm, is stored in the global variables moduie_draw_cp, 

_din/ _fp. 

The downloadable extensions are all passed an array of (x,y) coordinates 
which they draw. The points are produced by a generate_curve function, 
which involves a series of calls to a runtime support math function involving 
floating point arithmetic. The final list of points are, for the C-packet and di- 
rect-mode calls scaled, to screen coordinates. 

The _f p case is a bit different. It passes a list of floating point values which 
are scaled to the screen by the extension function. It illustrates how floating 
point values can be passed through TIGA. Currently TIGA does not support 
the passing of floating point parameters directly. The reason is not due to 
TIGA but to the fact that TMS340 floating point numbers are not in IEEE for- 
mat (and require conversion to and from IEEE format). The floating point ex- 
tension contains the source code of IEEE format conversion routines, which 
can be used for this. The TMS340 floating point format will be available in 
IEEE format in the near future, and direct floating point support will then be 
put into TIGA. 

4.8.2. 1 Speed Optimization of Paraiiel Processing 

The timing of the extensions is done in two ways: First, time is taken directly 
following the functions being invoked (without synchronization). This gives 
a much shorter time than the second set of timings, which are taken after 
a call to the synchronize function. In the first case the time measured isthat 
taken by the host. Second is the time taken by both the host and the 
TMS340. The TMS340 is a coprocessor and can offload much of the graphi- 
cal processing from the host and do it much faster. However, the time saved 
by an application also depends on utilizing both processes in parallel. If the 
application is written so that the host is simply waiting for the TMS340 to 
complete, then little or no time may be saved. 

When the application can perform an operation, say the calculation of the 
next set of graphical drawing coordinates, while the TMS340 is drawing, is 
whentthe best performance improvements are achieved. This is important 
when choosing the communication entry points to use. Entry points that re- 
turn values, such as cp_ret, cp_alt, clm_ret, dm_ptrx, etc. all cause the 
host to wait until the TMS340 is finished. If a downloadable extension, which 
takes a long time to execute, is to return status information, it is perhaps bet- 
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ter to split the function into two. One to do the drawing, the other to return 
the status. That way the host calling function can invoke the first function 
without waiting, then go on to perform some calculations that are not depen- 
dent upon the status, then call the status function some time later. This uti- 
lizes both processors more efficiently. 

4.8.2.2 Invoking Downloadable Extensions 

The Invocation of the three downloadable extensions brings out some fur- 
ther points that were not covered by the stars example. Referring to the #de- 
fines for the communication entry points: 

□i C Packet: This illustrates the passing of pointers in C-packet mode. No- 
tice that the third parameter c is also used to determine the size of the 
second parameter b. This is a very typical case. Unless a pointer is 
pointing to af ixed size structure, a parameter is needed to tell the calling 
function how big the array being passed really Is. This parameter can 
be used to tell the communication driver how much to send. The value 
may require scaling, as in this case, c refers to the number of vertices 
being passed, but as each vertex is made up of two 1 6-bit coordinates 
(x, y), the number of WORDS to be sent is c*2. 

Q Direct ModerThe direct-mode entry point dm_pcmcl allows the trans- 
fer of combinations of immediate data and pointers. The parameters 
are: 

- 1 number of immediate words being sent 

- a immediate word 

- 1 number of pointers being sent 

- c*4 number of BYTES to be sent in the pointer 

- b (far) pointer to the data 

Note that the c parameter is not sent explicitly as an immediate word. 
This is because since it is used as a count for the pointer data b, it ap- 
pears in the communication buffer multiplied by 4. Because the down- 
loaded extension can recreate it by a simple shift there is no point in 
sending it down twice. Notice too that the size Is sent in bytes not words 
as it is for C-packet. What ends up in the communication buffer is best 
seen by consulting the routine draw_curve_din. 

Q Floating Point: Although the floating point uses a DOUBLE_PTR 
which looks as aTlGA macro, it is defined in the curves program. TIGA 
treats doubles (which are the only floating point parameters passed to 
routines, floats are always promoted to doubles) as an array of 4 un- 
signed 16-bit words. Consult the function draw_curve_fp to see how 
the conversion of floating point occurs. Although this example does not 
show it, the altdouble_ptr can return floating point values from TIGA 
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4.8.3 ADI Driver Example 



The ADI directory contains tiie source of an example driver for ADI release 
3.1 which works with AutoCAD release 9. There is no discussion on how to 
write an ADI driver, since this is fully covered in the ADI Driver Development 
Kit that can be obtained from AutoDESK Corp. The only details given here 
are regarding certain features of TIGA utilized in this driver. 



4.8.3. 1 Installing an ALM 

The requirement for an ALM has been fully discussed in Section 4.1 .2 . The 
main program (in file adi . c) makes a call to create_alm to create the ALM 
from the RLM that is shipped with the driver. Then a trial call to install_alm 
is made, to see if there will be any problems in installing the ALM (for exam- 
ple, not enough heap) later. Toward the end of the main program, a call is 
made to the initialize function in the adiasm.asm file, to turn the program 
into a terminate-and-stay-resident task. Note that previously a call is made 
to set_videomode(PREVIOUS, to end the TIGA session and return the 
board to an IBM graphics mode, such as EGA. 

Later, when AutoCAD is invoked and a drawing is edited, AutoCAD makes 
a call to the pinit function (in adi.c). The pinit function calls 
set_videomode(TIGA, to start the TIGA environment and then calls 
install_alm to install the ALM. 

4.8.3.2 Linking the Extended Primitives with the User RLM 

There is no call to install_primitives in the ADI driver; although, some of 
the extended primitives are used in the driver. These primitives are linked 
in with the ADI driver primitives and are loaded simultaneously. Thus, in the 
adiext . asm file, references are made to TIGA extended functions such as 
drawjine, bitbit, etc. These primitives are supplied in TIGA both as an 
RLM and in the form of a library that can be linked. This library is referenced 
when the ADI RLM is created (see adiext . cmd). 

The advantage of linking the extended primitives with a user load module 
is that only those functions that are needed by the application are included, 
freeing up valuable space in TMS340 memory. Also, the time to load the 
functions is reduced. However, since the extended primitives are being 
loaded into a user module, their command numbers need to be modified. 
This is why their definitions appear in a header file adiext .h and why the 
TIGA extended primitive definitions appear in a separate include file ex- 
tend . h rather than in t iga . h. This enables their command numbers to be 
changed without the need to edit the standard TIGA include files. 
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4.9 Installing Interrupts 

Interrupt service routines contained witliin adynamic load module must be 
written as a function called with no arguments; that is, the last instruction 
should be a RETS instead of a RETI. This is because the TIGA graphics 
manager provides a general interrupt handlerthat invokes the interrupt rou- 
tines only if they are enabled. This handler performs the actual RETIinstruc- 
tion to return from the interrupt. 

In addition, the handler also provides for chaining of multiple Interrupt ser- 
vice routines on a single interrupt level. This is vital for the TMS340 proces- 
sor, which often has more than one display interrupt active. For instance, 
the graphics manager provides three interrupts to control a hardware emu- 
lated cursor, page flipping, and wait-scan, all using the display interrupt. 

The interrupt service routines must be installed into the general interrupt 
handler during the installation of a dynamic load module.The routines that 
are to become interrupt service routines must be written, compiled, and as- 
sembled. A specially named TIGAISR section mustthen be declared, identi- 
fying the name of each interrupt service routine and the level where it should 
be installed. The format of this section is explained in Section 4.2.2 on page 
4-5. During the download process, the information within this special sec- 
tion is used to chain interrupts into the TIGA interrupt handler, where each 
interrupt is assigned a priority level. The interrupt priority can be retrieved 
for each ISR declared in the TIGAISR section, after a successful installation, 
by performing a call to getJsr__prioritles. This routine returns an interrupt 
priority for each ISR in their order of declaration in the section. Each interrupt 
is also installed in a disabled state and must be explicitly enabled by the pro- 
grammer. 

The setjnterrupt function must be called to enable or disable a particular 
interrupt service routine. The interrupt level and the associated priority must 
be specified as arguments to this function. 

Note that it is possible for a downloaded extension to be executed from the 
host and, in turn, set the traps to its own server to avoid the overhead of the 
global interrupt handler in certain time-critical functions. However, care 
must be taken, especially in the display interrupt used by TIGA primitives 
such as the cursor functions. If equivalent support is not given to these func- 
tions, as provided by the global interrupt handler, certain TIGA primitives 
may not execute correctly. 



Certain TMS340 boards provide external connection to the LINT1 and 
LINT2 TMS340 processor pins. In such cases, interrupt service routines 
can be written for them using the techniques outlined here. However, such 
techniques are clearly not portable across all TMS340 processor boards. 
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4.9.1 Clock Example of Using Interrupts 



This example displays a real-time analog clock on the TMS340 screen, 
which is updated by the use of the timer interruptfunction Installed in the dis- 
play interrupt. 

The timer functions are trivial, as can be seen in the timer .asm file; they 
simply increase a count. There is an additional function get_time, which 
returns the value of the count to the host. Notice that the TIGAEXT section 
is included with the timer. Because this is an assembly language program, 
there is no need to keep TIGAEXT separate. There is an additional TIGAISR 
section, that is similar to TIGAEXT but holds an Interrupt level In addition. 

The installation of the interrupt service routine (ISR) is exactly the same as 
for a regular extension, except that directly after the call to instalLrIm is a 
call to getJsr_priorities (see main program of clock. c). These calls re- 
turn the priority value for each of the interrupt service routines installed. Note 
that this means that an array big enough to hold all these priorities must be 
declared prior to invoking getJsr_prlorlties to hold the values that will be 
returned. In this example only one ISR is installed, so a single short variable 
will suffice. The priority is used in the call to setjnterrupt to enable the in- 
terrupt. It is required, since TiGA allows any number of ISRs on a given in- 
terrupt level; thus the priority is the mechanism for identifying individual 
ISRs. 

Following the call to getJsr_prloritles is a call to setjnterrupt. This takes 
two parameters to identify the ISR (an interrupt level and a priority) and two 
parameters, which may be set; an enable/disable flag and adisplay line (the 
latter is valid only for display interrupts and is ignored by interrupts at other 
levels). 

After the interrupt is enabled, no direct reference is made to it. The function 
get_time is used to return the value of the count and thus determine the 
elapsed time. The get_tlme function in this example is not #defined; there 
is no absolute requirement to do this, but it is also clear that the code is less 
readable because of it. 
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4.9.2 Ball Example Using Interrupts 

This example demonstrates many of the same features of the previous ex- 
ample with one major exception. The interrupt service routine performs 
some graphics operation (in the form of drawing a ball on the screen). Be- 
cause the graphics operation uses implied operands in the B-file and I/O 
registers that cannot be guaranteed to be correct (since the interrupted rou- 
tine could be using the OFFSET or DPTCH B-file registers as temporaries), 
the interrupt service routine has to set up these values. Because this in- 
volves over-writing their current values, they must first be saved some- 
where. In this example they are saved in a global structure, by the routine 
setup_gsp_env. In an actual application, the registers could be pushed onto 
the stack using an MMTM instruction, if this function were receded in 
TMS340 assembly. The graphics registers are then initialized using the val- 
ues from the global structures such as CONFIG. After the ISR has com- 
pleted, the restore_gsp_env function is called to restore the register values 
prior to returning to the interrupted function. 
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4.10 The TIGA Linking Loader 



The TIGA linking loader tigalnk is tlie meciianism by wiiich extensibility 
is made possible. It is a full TMS340 iinl<er that provides the capability of re- 
solving references to TIGA graphics manager (GM) functions, tigalnk is 
a full COFF loader which provides the capability of relocating object code 
anywhere in TMS340 memory. It is fully portable, using the TIGA communi- 
cation driver to interface to any TMS340 board that has TIGA ported to it. 
TIGALNK has extensibility control built into it, so that it can read the TIGAEXT 
and TIGAISR sections and inform the graphics manager of the user exten- 
sions that are to be Installed. 

The linking loader is invoked by several TIGA primitives for installing exten- 
sions into TIGA, and for performing various other tasks. Applications and 
devicedrivers written for TIGA should restrict themselves to the TIGA primi- 
tives and never invoke the linking loader directly, as the linker is subject to 
change in future revisions of TIGA, while the procedural interfaces will re- 
main the same. A list of linking loader flags with their procedural equivalents 
is given in the list below: 



Option Files 


Description 


Equivalent Function 


-ca RLMNAME , ALMNAME 


Link, then create an ALM 


create_alm 


-CS COFFNAME 


Create external symbol table 


create.esym 


-ec RLMNAME 


Check the RLM for errors 


none 


-fs SYMNAME 


Flush external symbol table 


flush_esym 


-la ALMNAME 


Load ALM into GM 


install_alm "^ 


-Ir RLMNAME 


Link, then load into GM 


instalLrIm 


-Ix COFFNAME 


Load and execute COFF file 


ioad_coff 
/gsp_execute 


TIGALNK can install an ALM. This is not done by the install_alm function, but by a function 


in the communication driver 


'. 





Below is a detailed description of the tigalnk options. Note that these op- 
tions can be placed anywhere on the command line; they do not have to be 
placed before filename arguments. 

in addition to the flags are a -q (quiet) option and a -v (verbose) option. If 
no options are specified, then the linker assumes normal command line op- 
eration and all working messages and error messages are displayed nor- 
mally. Selecting quiet mode operation suppresses all textual messages, 
and only error codes are returned upon termination (this mode is used in the 
procedural interface). In verbose mode operation, the linker provides mes- 
sages during every internal operation. 
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4.10.1 /ca - Create Absolute Load Module 

This option creates an absolute load module ( . alm) from the specified relo- 
catable load module ( .rlm). If the name of the output ALM file is not speci- 
fied on the command line, then the base name of the RLM file is used, but 
with a forced file extension of .alm. Also, if no path information is supplied 
for the output file, then it is placed in the path specified by the -i option of 
the TIGA environment variable. 

4.10.2 /cs - Create External Symbol Table 

This option reads the symbolic information from the specified COFF file and 
places it in TIGA340.SYM, or if the optional command line argument was spe- 
cified, in the Symbol filename supplied. 

4.10.3 /ec - Error Check 

This command line option can be used to check the integrity of an RLM prior 
to installing it. The TIGA graphics manager does not have to be active in or- 
der for this option to work, but if it is, the largest amount of available heap 
that can be used to load RLMs is also displayed. 

Once executed, the /ec option scans the specified RLM and prints out the 
number of extensions or interrupt service routines contained within the mod- 
ule. If none are present, that is, no .TIGAEXT or .TIGAISR section is pres- 
ent, then a warning message is displayed. The amount of heap required to 
load the module is then displayed, and if the graphics manager is active, the 
largest available block of TMS340 heap is also displayed. 

If the module contains any unresolved references that would not be resolved 
at load time, these are printed out. This allows the user to resolved symbol 
references before actually attempting to download and install the file. 

I I 

Note: 

Only symbols contained in the TIGA external symbol file (TIGA3 4 . sym) are 
used to resolve symbol references. As supplied, or after creation by the /ix 
or /cs option, this file contains only the symbols for tigagm. out, the TIGA 
core primitives. If the module being checked contains references to other 
modules, such as the TIGA extended primitives, then these must be loaded 
prior to performing the check. 

I I 

Example: 

TIGALNK /LX H - load and OXOCUte TIGAGM. OUT 



TiGALNK /LR extprims Q " ^oa6 TIGA extended primitives 

(extprims.rlm) 



TIGALNK /EC user |g| - Check Integrity Of user. rlm 
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4.10.4 /fs - Flush External Symbol Table 

This option f lusties ail but tiie symbois reiated to tigagm . out from tiie exter- 
nai symboi tabie, tiga340 . sym. As tiie symbois for eacii instaiied moduie 
are deleted, a call to tiie TIGA grapiiics manager is also made to delete tiie 
module from TMS340 memory. 

4.10.5 /la- Load and Install an Absolute Load Module 

This option loads and installs an ALM into the active TIGA graphics manager 
running on the target such that functions contained in the module can be in- 
voked from the host. 

I 1 

Note: 

ALI\/ls contain no symbolic information, so modules loaded after an ALM 
cannot make references to symbols contained within an ALM. 



4.10.6 /ir - Load and Install a Relocatable Load Module 

This option loads and installs an RLM into the TIGA graphics manager so 
that functions contained in the moduie can be invoked from the host. 

Symbols contained In the module are added to tiga340 . sym, the external 
symbol table, so thatthey can be referenced by modules loaded afterwards. 

4.10.7 /ix - Load and Execute a COFF File / Execute TIGA GM 

This option has the ability to perform two distinct functions, depending on 
whether or not a COFF file is specified as a command line argument. If a 
COFF file name is provided on the command line, then it is loaded and ex- 
ecuted much like the stand-alone COFF loader provided with the Tl soft- 
ware development board. 

If a COFF file name is not provided, then it is assumed that the TIGA graph- 
ics manager is to be loaded and executed, in this case, two additional func- 
tions are performed after tigagm . out is loaded and executed. The TIGA ex- 
ternal symbol file (tiga340 . sym) is created, and the symbols contained in 
TIGAGM. OUT are written to it. Once complete, a call to the TIGA communica- 
tion driver function handshake is performed to initialize communications be- 
tween the host and the TMS340. 
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This appendix contains the data structures used in TIGA. They are defined 
In the include file typedef s .h. 

Section Page 

A.1 Integral Data Types A-2 

A.2 CONFIG Structure A-3 

A.3 CURSOR Structure A-5 

A.4 ENVIRONMENT Structure A-6 

A.5 FONTINFO Structure A-7 

A.6 MODEINFO Structure A-11 

A.7 MONITORINFO Structure A-13 

A.8 OFFSCREEN Structure A-14 

A.9 PAGE Structure A-15 

A.10 PALET Structure A-16 

A.11 PATTERN Structure A-17 

The structure definitions supplied refer to the C syntax. In the assembly lan- 
guage equivalent file, typedef s . inc, the structure name precedes every 
field name. Thus, the hot_x field in the cursor structure becomes cur- 
sor_hot_x. This is because in the macro assembler all fields must be 
unique. Note that this also applies to the TMS340 side equivalent file 
gsptypes . inc. This file also has all type definitions in uppercase. The two 
TMS340 side type definition files gsptypes .h and gsptypes . inc contain 
additional type definitions internal to TIGA and are not generally of use to 
the applications programmer. 
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A.1 Integral Data Types 

The TIGA data structures use the following type definitions throughout: 

typedef unsigned char uchar; 

typedef unsigned short ushort; 

typedef unsigned long ulong; 

typedef unsigned long PTR; 

typedef uchar far *HPTR; 
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A.2 CONFIG Structure 



This structure contains the configuration information. Part of this structure 
is the MODEINFO structure defined in Section A.6, which describes the 
board configuration. If alternate configurations are available, they can be set 
using setjconfig. 



typedef struct 
{ 

ushort 

ulong 

ulong 

ulong 

ushort 

ushort 

ulong 

ulong 

ulong 

ulong 

ulong 

ulong 

HPTR 

PTR 



MODEINFO mode; 
} CONFIG ; 



version_number; 

coinm_buff_size; 

sys_flags; 

device_rev; 

nuin_niodes; 

cur r ent_mode ; 

program_mem_start ; 

pr ogr am_mem_end ; 

display_mem_start ; 

displaY_mem_end; 

stack_size; 

shared_mem_size; 

shared_host_addr; 

shared_gsp_addr; 



The CONFIG structure consists of the following fields: 



version number 



comm buff size 



sys flags 



device rev 



num modes 



current mode 



TIGA revision number, assigned by Texas instru- 
ments. 

Size, in bytes, of the communications buffer; appli- 
cation needs to ensure that the data sent does not 
overflow this buffer, for commands that do not check 
the size of the downloaded data. 

Bits — 7 indicate FPUs (Floating Point Units) are 
present to be compatible with the TMS34020 copro- 
cessor ID codes. Bits 8 —15 are reserved. 

This function invokes the TMS340's REV instruction 
and returns its result here. 

Number of extended modes, for boards that allow the 
switching between different display setups. 

Mode number corresponding to the current operating 
mode. 



program_mem_start Start address of program memory. 
program_mem_end End address of program memory. 
dispiay_mem_start Start address of display memory. 
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di splay_mein_end 

stack_size 

share_mem_size 

share_host_addr 
share_gsp_addr 



End address of display memory. 

Default stack size; can be modified using gsp_minit. 

Size (In bytes) of shared memory that Is available for 
the application to use. 

If share_size Is nonzero, It Is the start address In 
host memory of the shared memory; otherwise it is 
undefined. 

If share_size Is nonzero, It Is the start address In 
TMS340 memory of the shared memory; otherwise, it 
is undefined. 
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A.3 CURSOR Structure 



This structure defines the cursor shape parameter for the set_curs_shape 
function. 

typedef struct 
{ 

short hot_x; 

short hot_y; 

ushort width; 

ushort height; 

ushort pitch; 

ulong color; 

ushort mask_rop; 

ushort shape_rop; 

PTR data; 
} CURSOR; 

This structure consists of the following fields: 

hot_x Offset x-coordinate added to the top left corner of the 

cursor shape to define the pixel specified by the 
set_curs_xy. 

hot_y Offset y-coordinate added to the top left corner of the 

cursor shape to define the pixel specified by the 
set_curs_xy. 

width Width of the cursor shape in pixels. 

height Height of the cursor shape in pixels. 

pitch Linear difference in the addresses of successive 

rows of the cursor shape (in bits). 

color Foreground color index with which the cursor is 

drawn. 

mask_rop Pixel processing operation used when applying the 

mask data to the background. This is normally speci- 
fied as AND. 

shape_rop Pixel processing operation used when drawing the 

shape of the cursor onto the screen. This is normally 
specified as OR or XOR. 

data Pointer to TMS340 memory containing two contigu- 

ous arrays of width by height.The first array is the 
mask data with Os where the cursor is located and 1 s 
elsewhere. The second array is the shape data, 
which has 1 s where the cursor is located and Os else- 
where. 
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A.4 ENVIRONMENT Structure 

The ENVIRONMENT structure contains the TIGA drawing environment 
global variables. 

typedef struct 
{ 

ulong xyorigin; 

ulong pensize; 

PTR patnaddr; 

PTR srcbm; 

PTR dstbm; 

unsigned long stylemask; 
} ENVIRONMENT; 

The ENVIRONMENT structure consists of the following fields: 
xyorigin Current drawing origin in y ::x format set by set_draw_orlgin 
Current pen size arranged in y::x format, set by set__pensize 
TMS340 address of current pattern, set by set_patn 



pensaze 

patnaddr 

srcbm 



dstbm 



TMS340 address of current source bitmap structure, set by 
set_srcbm 

TMS340 address of current destination bitmap structure, set 
by set.dstbm 



stylemask Current line style mask used by styledjine function 
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A.5 FONTINFO Structure 



The text rendering capabilities included as part of the TIGA extended primi- 
tives are very rich, providing the application writer with the ability to display 
everything from simple, fixed cell type text, such as that used by dumb termi- 
nals and EGA, VGA graphics adapters, to the desktop publishing type (Wysi- 
wyg) text, where the height and width of characters, along with the style and 
size can vary. 

The fonts used for text rendering are a collection of characters having a 
unique combination of height, width, style, and other attributes. The format 
of these fonts are unique to TIGA and are described in the following para- 
graphs: 

The characters within a font have an associated two-dimensional bitmap 
that defines the shape of the character. When the text is rendered. On bits 
(1s) within a character bitmap are expanded to pixels in the active fore- 
ground color, as set by the set_fcolor function. Off bits (Os) are expanded 
pixels in the background color. The format of a font is defined by the follow- 
ing data structure: 

typedef struct 

{ 

short magic; /* TIGA Identifier */ 

long length; /* length of font in bytes */ 
char f acename [ 32 ] ; 

short first; /* ASCII code of first character */ 

short last; /* ASCII code of last character */ 

short maxwide; /* maximum character width */ 

short maxkern; /* maximum character kerning amount */ 

short charwide; /* char, width (0 if proportional) */ 

short avgwide; /* average width of characters */ 

short charhigh; /* character height */ 

short ascent; /* ascent (how far above base line) */ 

short descent; /* descent (how far below base line) */ 

short leading; /* leading (row bott.to next row top) */ 

PTR fontptr; /* address of font in GSP memory */ 

short id; /* id of font (set at install time) */ 

} FONTINFO; 

The following Is a description of the FONTINFO structure parameters. Pa- 
rameters 8, and 10 through 13 are shown in Figure A-1. 

1) magic 

This field is an identifier for the data structure. It consists of three parts: 
bits 00 — 01 : data structure sub type 
bits 02 — 07: data structure type 
bits 08—15: TIGA identifier 

For the bitmap fonts described here, the magic identifier is filled in as 
follows: 
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bits 00 — 01 : (FONT subtype = bitmap) 

bits02 — 07:1 (FONT) 

bits 08 — 1 5: 0x80 (Indicates TIGA font formati .x) 

For this particular font data structure, the magic number value Is 
0x8040. In the future, TIGA may support outline or stroke fonts, in which 
case the font subtype would change. 

2) length 

The length of the entire font in bytes. This is useful when allocating 
memory for a font and for reading it from disk. 

3) facename 

A NULL terminated string of ASCII characters up to 32 long containing 
the name of the font. Example: Tl Roman, Tl Helvetica, etc. 

4) first 

ASCII code of the first character defined inthefont. For example, if first 
was 0x20, the ASCII code for a space character, then that is the lowest 
ASCII code for which a bitmap is defined in the font. 

5) last 

ASCII code of the last character defined in the font. 

6) maxwide 

The width of the widest character defined in the font. 

7) maxkern 

The maximum kern for any character within the font, expressed as a 
positive value. For example, if kerning was 3, then the maximum any 
character will back up to overlap the previous drawn character is 3. 

8) charwide 

The character width is the image width of the character, plus the space 
separating this character from the next. If the character width is zero, 
then the width of characters within the font varies. In that case an entry in 
the offset/width table specifies the width for each character. 

9) avgwide 

The average width of characters within the font. This is the cell width of 
all defined characters within the font (not considering any kerning or ex- 
tra intercharacter spacing) divided by the number of characters defined. 
It is useful when selecting a font for a best fit at varying target resolu- 
tions. 
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10) charhigh 

The character height is the sum of the ascent and decent. It is constant 
throughout any particular font but may vary between fonts. 

11) ascent 

The ascent is the number of vertical pixels from the base line to the top of 
the font cell. 

12) descent 

The descent is the number of vertical pixels from the base line to the 
bottom of the cell. 

13) leading 

This term comes from the fact that typesetters often used strips of lead 
to adjust spacing between rows of characters when building a plate to 
be printed with a printing press. For bitmap fonts, this value is the num- 
ber of pixels recommended by the font designer that should be skipped 
between rows of characters, that is, if the leading is 3, then 3 pixels 
should be skipped between the descent line of a row of characters, and 
the ascent line of the row of characters drawn directly beneath. 
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Some of the fields in the font structure are illustrated in Figure A-1. The 
numbers refer to the numbered sections in the parameter description. 



Figure A-1. Bitmap Font Format 
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In addition, Figure A-1 illustrates the following font characteristics: 

a) Base Line 

The base line is an invisible reference line corresponding to the bottom 
of the characters, not including the descenders. 

b) Character Origin 

The character origin isthatpartof a character corresponding to a speci- 
fied drawing location. This origin may vary, depending on the text align- 
ment attribute used to draw text. The default text alignment is relative to 
the top left corner of the character cell. Alignment can also be set rela- 
tive to the leftmost point on the character baseline by performing a call to 
set_textattr. Baseline origin is useful when a string of characters con- 
sists of different size or style fonts, in which case the baseline should 
remain constant throughout the text. 

c) Image Width 

The image width is the number of bits of the portion of the character pat- 
tern bitmap containing the actual character image. This width does not 
include any blank space to the left or right of the character when it is 
displayed and can vary within a font and between fonts. 
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A.6 MODEINFO Structure 



This structure contains all the configuration information that can vary on a 
specific board. It is part of the configuration structure returned by 
get_config (which returns only the MODEINFO for the currently installed 
mode). The total possible modes can be inquired using get_modeinfo. 

typedef struct 
{ 

ulong disp_pitch; 

ushort disp_vres; 

ushort disp_hres; 

short screen_wide; 

short screen_high 

ushort disp_psize; 

ulong pixel_mask; 

ushort palet_gun_depth 

ulong palet_size; 

short palet_inset; 

ushort num_pages; 

short num_offscrn_areas; 

ulong wksp_addr;. 

ulong wksp_pitch; 
} MODE INFO; 

The MODEINFO structure consists of the following fields: 



disp_j)itch 

disp_vres 
disp_hres 
screen_wide 

screen_high 

disp_psize 
pixel mask 



palet_gun_depth 



Display pitch: linear difference between two scan 
lines in bits. 

Vertical resolution in scan lines. 

Horizontal resolution in pixels. 

Contains the width of the monitor in centimeters. For 
systems where these dimensions are unknown, set 
to1. 

Contains the height of the monitor in centimeters. For 
systems where these dimensions are unknown, set 
to1. 

Pixel size. 

Contains a mask of the bits used in a pixel. It will nor- 
mally contain the value of 2 to f/7epoi/verdisp_psize 
minus 1, indicating that every bit of pixel data is perti- 
nent. On some boards, the frame buffer may be ar- 
ranged by 8 (disp_psize = 8) but With only 6 bits 
implemented. In that case, pixel mask would contain 
the value 63 (hexadecimal 3F). 

Number of bits per gun in palette. 
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paiet_size Number Of entries In the palette. 

paiet_inset For most systems, this field is set to 0. For 

TMS34070-based boards, which store the palette In 
the frame buffer, this is the offset from the start of the 
scan line to the first pixel data. 

num_j>ages Number of display pages In multi-buffered systems. 

num_of f scrn_areas This Is the number of offscreen memory blocks avail- 
able. If nonzero, then it is used to allocate space for 
the offscreen array, which can be obtained from the 
TMS340 via a call to the get_offscreen_memory 
function. 

wksp_addr Starting linear address in memory of offscreen work- 

space area. 

wksp_pitch Pitch of offscreen workspace area. If wksp_pitch = 

0, then no offscreen workspace is currently allocated. 
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A.7 MONITORINFO Structure 



This structure is not of general interest to an application writer. It is used by 
the OEM porting TIGA to its board to specify the values of the video timing 
parameters for a particular mode. Note that this structure is board-specific. 
An OEM is free to add to this structure its own OEM-specific video timing 
information. This structure will invariably change for a TMS34020 version 
of TIGA. 

typedef struct 
{ 

ushort hesync; 

ushort heblnk; 

ushort hsblnk; 

ushort htotal; 

ushort vesync; 

ushort veblnk; 

ushort vsblnk; 

ushort vtotal; 

ushort dpyctl; 

ushort screen_delay; 

ushort flags; 
} MONITORINFO ; 

The MONITORINFO structure consists of the following fields: 



hesync 
heblnk 
hsblnk 
htotal 
vesync 
veblnk 
vsblnk 
vtotal 
dpyctl 



value loaded 
value loaded 
value loaded 
value loaded 
value loaded 
value loaded 
value loaded 
value loaded 
value loaded 



nto the HESYNC I/O register 
nto the HEBLNK I/O register 
nto the HSBLNK I/O register 
nto the HTOTAL I/O register 
nto the VESYNC I/O register 
nto the VEBLNK I/O register 
nto the VSBLNK I/O register 
nto the VTOTAL I/O register 
nto the DPYCTL I/O register 



screen_deiay Numberofframesthatthescreenlsblankwhenloadingthe 
video registers. This allows a monitor time to synchronize 
to the new timing before the screen is unblanked. 



flags 



Monitor desription flags. Current flags defined are = color 
monitor, 1 = monochrome monitor. 
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A.8 OFFSCREEN Structure 



This structure defines tfie offscreen areas returned by tlie 
get_offscreen_memory function. 

typedef struct 
{ 

PTR addr; 

ushort xext; 

ushort yext; 
} OFFSCREEN_AREA; 

Tiie OFFSCREEN structure consists of the following fields: 
addr Address in TMS340 memory of an offscreen work area. 
xext X extension of the offscreen area in the current screen pixel size. 
yext y extension of the offscreen area in the current screen pixel size. 
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A.9 PAGE Structure 



This structure is not of general interest to an application writer. It is used by 
the OEM porting TIGA to his board to specify the start addresses of the dis- 
play page (the value loaded into the display start I/O Register) and drawing 
page (the value loaded into the offset B-file register). This structure is used 
to support multiple display pages used by the page_f lip function. Note that 
this structure is board-specific and may change in future versions of TIGA. 

typedef struct 
{ 

PTR BaseAddr 

ushort DpyStart 

short DummyPad; 
}PAGE; 

The PAGE structure consists of the following fields: 

BaseAddr Baseaddressofstartofdrawingpage;thisvalueis loaded Into 
the OFFSET B-file register. 

DpyStart Base address of start of display page; this value is loaded into 
the Display Start I/O register. 

DummyPad 1 6 bits to pad Structure to power of 2 size. 
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A.10PALET Structure 



This structure contains tlie red, green, blue, and intensity components for 
a palette entry. 

typedef struct 
{ 

uchar r; 

uchar g; 

uchar b; 

uchar i; 
} PALET; 

This structure consists of the following fields of the palette entry: 
r Value of the red gun 

g Value of the green gun 

b Value of the blue gun 

i Value of the intensity 
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A.11 PATTERN Structure 



The PATTERN structure defines the pattern shape information passed to 
the set_patn function. 

typedef structure 
{ 

ushort width; 

ushort height; 

ushort depth; 

PTR data; 
} PATTERN; 

This structure consists of the following fields: 

width Width of the pattern in bits. 

height Height of pattern in bits. 

depth Depth (bits/pixel) of pattern. 

data Pointer to pattern data in TMS340 memory. 
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Appendix B 

Graphics Output Primitives 



This appendix describes some of the assumptions made in the design of 
the TiGA graphics output primitives which are part of the extended primi- 
tives, it also describes the conventions adopted regarding the drawing, 
mapping, and filling with pixels to represent mathematical functions on a vid- 
eo screen. This appendix includes the following sections: 

Section Page 

B.1 Categories of Graphics Output Primitives B-2 

B.2 Fill Patterns B-4 

B.3 l\/Iapping Pixels to XY Coordinates B-5 

B.4 Area Filling Conventions B-6 

B.5 Vector Drawing Conventions B-7 

B.6 Drawing Pen B-8 

B.7 Color Selection B-9 
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B.I Categories of Graphics Output Primitives 

The graphics functions draw several shapes in a variety of styles. Table B-1 
describes the figure types and drawing styles. Table B-2 shows the shapes 
that can be drawn in a particular style. The column headers list the available 
styles and the row headers list the available shapes; a check mark indicates 
that a shape can be drawn with a particular style. 

Table B-1. List of Function Types and Drawing Styles 



Function Types 


Function 
Name 


Description 


line 


A straight line. 


oval 


Ellipse in standard position (major and minor axes parallel to coordinate 
axes). 


ovalarc 


An arc of an ellipse in standard position, specified in terms of beginning and 
ending angles. 


point 


A single pixel or pen image drawn at the indicated XY coordinate pair. 


polygon 


A filled region defined by a collection of straight edges. Both convex 
polygons and arbitrarily complex polygons are supported. 


polyline 


A collection of straight lines. Figures made up of many lines can be drawn 
more efficiently by using the polyline commands than by repeated calls to 
the line functions. 


piearc 


Pie arc or wedge. Similar to ovalarc, but with addition of sides drawn from 
center of ellipse to arc endpoints to produce a closed figure. 


rect 


Rectangle with vertical and horizontal sides. 


seed 


Fill connected set of pixels beginning at specified seed point. 
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Drawing Styles 


Function 
Name 


Description 


draw 


Draws figure outline one pixel wide using background color. 


fill 


Draws figure interior filled in solid background color. 


frame 


Draws frame in solid background color. Horizontal and vertical 
thicknesses of frame border are both specified. 


patnframe 


Draws frame, using pattern in the foreground and background colors. 
Horizontaland vertical thicknesses of frame border are both specified. The 
pattern is programmable. 


patnpen 


Draws figure outline using pen and pattern in the foreground and 
background colors. Pen size and pattern are programmable. 


pen 


Draws figure outline using pen in solid background color. Pen is 
rectangular with programmable height and width. 


patnfiil 


Draws figure interior filled with pattern in the foreground and background 
colors. The pattern is programmable. 



Table B-2. Checklist of Available Figure Types and Drawing Styles 





Drawing Sf, 


vies 


Figure 
Type 


draw 


pen 


patnpen 


fill 


patnfiil 


frame 


patnframe 


line 


. V 


V 


V 


N/A 


N/A 


N/A 


N/A 


oval 


V 






V 


V 


V 


V 


ovalarc 


V 


V 


V 










piearc 


V 


V 


V 


V 


V 






point 


V 


V 


V 


N/A 


N/A 


N/A 


N/A 


polygon 


N/A 


N/A 


N/A 


V 


V 


N/A 


N/A 


polyline 


V 


V 


V 


N/A 


N/A 


N/A 


N/A 


rectangle 


V 






V 


V 


V 


v 


seed 


N/A 


N/A 


N/A 


V 


w 


N/A 


N/A 
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B.2 Fill Patterns 



Graphics functions that include patn as part of their names draw with a pat- 
tern instead of a solid color. The pattern is currently limited to a 1 6 x 1 6 bit- 
map and is represented in memory as an array of 256 contiguous bits. The 
bits in a pattern are listed in left-to-right order within a row, and rows are 
listed in top-to-bottom order. 

Figure B-1 shows an example of a pattern as it appears on the screen. The 
small squares represent individual bits in the pattern; shaded squares rep- 
resent 1s, and white squares represent Os. The bit at the top left corner is 
the first bit (bit 0) in the pattern array. The bit at the lower right hand is the 
last bit (bit 255) in the array. 



Figure B-1. A 16x16 Pattern 

'iTi-ri^rj-rj-rT'-rT-\- 

1-4-1 
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When a pattern is drawn to the screen, the Os in the bit map are replaced 
with the background color, and the Is in the bit map are replaced with fore- 
ground color. The pattern is mapped into 16x16 cells on the screen. The 
X and Y coordinates at the top left corner of each cell are both multiples. 
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B.3 Mapping Pixels to XY Coordinates 

Figure B-2 illustrates the conventions that are used to map XY coordinates 
to pixels on the screen. The filled area is a rectangle of width w = 5 and 
height = 3, whose top left corner is located at XY coordinates (4,2). The fill 
is performed by the following function call: 

fill_rect(5, 3, 4, 2) 

Pixels lying within the perimeter of the specified rectangle are turned on to 
represent the fill area. By convention, X increases from left to right, and Y 
increases from top to bottom. The default drawing origin is at the upper left 
corner of the screen. (The origin may be relocated at an arbitrary position 
on or off screen with a call to the set_draw_origin function.) The XY coordi- 
nates passed to graphics routines are constrained to be integer values. The 
coordinate grid is overlayed on the screen so that integer XY coordinate 
pairs coincide with pixel corners (not with pixel centers). The conventions 
used for determining which pixels are selected to represent filled areas and 
infinitely thin vectors are explained in the following sections. 

Figure B-2. Rectangle Fill 




h-w = 5-H 
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B.4 Area Filling Conventions 



Figure B-3 shows a filled polygon, in wliich afill_polygon function defines 
the fill area indicated by the straight edges in the figure. The rule for deter- 
mining whether a pixel is selected as part of the fill area is as follows: if the 
center of the pixel falls within the mathematical boundary of the area, it is 
turned on to indicate that is part of the fill area. (If a pixel's center falls pre- 
cisely on the boundary between two areas, by convention the pixel is consid- 
ered to be part of the area immediately below and to the right of the pixel). 
Pixels whose centers lie outside the boundary are not considered part of the 
fill region. The same principles are applied to the filling of other shapes (el- 
lipses and thick lines drawn with a rectangular drawing pen, for example). 

Graphics functions that follow the above conventions for filled areas are all 
functions whose names include the modifiers fill, pen, or frame. 



Figure B-3. Polygon Fill 
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B.5 Vector Drawing Conventions 

Points, lines, and arcs are defined mathematically to be infinitely thin. Be- 
cause these figures contain no area, they are invisible if drawn using the 
conventions for filled areas. A different set of conventions must be used to 
make points, lines, and arcs visible. These are the vector drawing conven- 
tions (to distinguish them from the area filling conventions). Vector drawing 
conventions apply to all functions whose names include the modifier draw. 

The vector drawing conventions associate the point identified by the integer 
coordinate pair (X,Y) with the pixel located to its lower right; that is, the pixel 
whose center is located at coordinates (X+1/2,Y+1/2). For example, the 
draw_point (7,io) command turns on the pixel at (7.5,1 0.5). As a second 
example, the polygon from Figure B-3 is shown again in Figure B-4 but is 
outlined rather than filled. (The draw_polylme function is used.) The points 
selected to represent the right side of the polygon are indicated as small 
black dots. The pixel to the lower right of each point is turned onto represent 
the edge of the polygon. 

A line or arc drawn using the vector drawing conventions consists of a con- 
nected set of pixels. This means that the line or arc is drawn as a continuous 
set of pixels that connect (or touch) horizontally, vertically, or diagonally, 
without gaps or holes in between. 

Figure B-4. Polygon Outline 
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B.6 Drawing Pen 



The drawing commands that use vector drawing conventions can draw only 
pixel thick lines and arcs. To draw lines and curves of arbitrary thickness, 
a rectangular pen (or brush or logical pixel) is used. Graphics functions that 
use the drawing pen have names containing the modifier pen. 

The graphics commands can be used to set the drawing pen's height and 
width to arbitrary positive, nonzero values. The pen is rectangular, and its 
position is identified by its top left corner. For example, when a pen of width 
w and height h draws a point at (X,Y), the resulting rectangle's top left cor- 
ner lies at (X,Y), and its bottom right corner lies at (X+w, Y+h). The rectangu- 
lar areacovered by the pen is filled eitherwithasolidcolororwith the current 
pattern, depending on the function used. 

The area underthe drawing pen is filled according to the area-filling conven- 
tions described previously. When the width and height of the drawing pen 
both equal 1 , a line or arc drawn by the pen is similar in appearance to that 
drawn by a function following the vector drawing conventions. However, the 
pen functions conform to the area-filling conventions, so a pen function can 
track more faithfully the perimeter of a filled area than a corresponding draw 
function. 

For example, consider an ellipse defined by some width w, height h, and 
coordinates (x, y). If adraw_oval(w, h, x, y) function call outlines afilled el- 
lipse drawn by a fill_oval(w, h, x, y) function, the draw_oval function may 
not in all instances select the same perimeter pixels as the filled ellipse. This 
can leave gaps between the filled area and the outline. In contrast, a 
pen_oval(w, h, x, y) function call follows the filled ellipse precisely, remain- 
ing flush to the ellipse at all points along the perimeter. 
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B.7 Color Selection 



The TIGA standard enables applications to be ported from one TMS340 
board to another. One of the most difficult parts of the porting process is en- 
suring that the colors chosen for the application are distinguishable (if not 
identical) when the application is run on another board. Palettes vary from 
board to board, sometimes considerably. This section describes the TIGA 
methodology concerning color selection. 

The configuration structure returned in get_config, contains the 
disp_psize element, which the application can use to determine the num- 
ber of colors that can be on the screen at any given time. The application 
must interrogate this value to determine if this number is sufficient, and 
double-up if necessary, painting different geometries with the same color. 

Selecting the colors isdone viatheset_palet, or set_palet_entry functions 
for a RAM-based palette. Because the palette may be ROM-based (making 
it impossible to set the palette entries), the f unctionjmplemented func- 
tion should be used on the set_palet functions prior to invoking them. If they 
are not implemented, the palette can be assumed to be ROM-based and a 
technique described later can be used to select colors. For RAM-based pa- 
lets, each entry can be set via a call to set__palet, which takes as its parame- 
ters an 8-bit value of red, green, blue, and intensity. 

For color monitors, the intensity field is ignored and the R-G-B values are 
used to load the palette entry. Because the palette may only use 4 or 6 bits, 
It takes the most significant portion of the 8-bit palette entry to set the color. 
The number of bits for each color gun is stored in the paiet_gun_depth 
field of the CONFIG structure. Alternatively, the getjsalet function will re- 
turn the physical colors stored in each entry (as opposed to the logical colors 
requested by the set_palet function) .Thus, colors can be chosen and speci- 
fied directly with this approach. For monochrome monitors, only the intensi- 
ty field is used, to specify the level of the grey scale for each entry. Again, 
the most significant bits are used when the palette entry size is less than 8 
bits. Thus, for RAM-based palettes, the application should specify both a 
color and monochrome values for each color index used. 

For ROM-based palettes, the get_nearest_color function can be used to 
inquire which color index to use. This function operates in reverse to the pre- 
vious case where instead of setting an 8-bit red, green, blue color index with 
a desired value, the nearest one to the desired value is returned to the call- 
ing application. Again, an independent grey-scale value for each color index 
must also be requested for ROM-based monochrome monitors. 

In summary, the application must test f unctionjmplemented on set_pa- 

let to determine whether the palette is ROM- or RAM-based. If it is 
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RAM-based, the application can select its palette directly and must do so 
in both R-G-B and intensity values for monochrome monitors. If the palette 
is ROM-based, the application must use get_nearest_color on each of its 
desired palette entries to set up the color indices, again specifying both color 
and monochrome values. 

Finally, there is also a short cut: if the init_palet function is implemented 
(which is the case in RAM-based palettes with 4 bits-per-pixel or more), the 
palette values after initialization are those stated in the init_palet function. 
The palette values are declared symbolically in an insert file tiga .h, and 
if these values are acceptable, they can be used directly by an application. 



B-io Graphics Output Primitives 



Appendix C 

TIGA Reserved Symbols 

< A ,'!/--y»'^'> 'V«"*v^v--s 'v^f*^s$»v "'V* jsa'&^^jM* ", ''W^}it^' r^,''iiS''^ 



Section Page 

C.1 Reserved Functions C-2 

C.2 TIGA Core Primitive Symbols C-3 

C.3 TIGA Extended Primitive Symbols C-5 



C-1 



Reserved Functions 



C.I Reserved Functions 



TIGA currently reserves the following functions for internal use. Do not 
chose function names that conflict with these. Avoid calling functions from 
an application program, since future versions of TIGA may not contain these 
functions. 

addjnterrupt 

add_module 

deLalLmodules 

deljnterrupt 

del_module 

get_memseg 

get_module 

get_msg 

get_state 

get_xstate 

gmjs_alive 

handshake 

init_cursor 

initjnterrupts 

init_video_regs 

makename 

oemjnit 

read_hstaddr 

read_hstadrh 

read_hstadrl 

read_hstctl 

read_hstdata 

rstr_commstate 

save_commstate 

set_memseg 

set_msg 

set_xstate 

write_hstaddr 

write_hstadrh 

write_hstadrl 

write_hstctl 

write hstdata 
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C.2 TIGA Core Primitive Symbols 

TIGA currently uses the following symbols in its core primitives and for the 
TMS340 C environment. To guarantee succesful operation, do not use 
downloadable extensions that conflict with any of these symbols. 

if the extension Is also to work with the extended primitives, then Section 
C.3 should also be considered when selecting symbol names. 



.bss 
.data 
.text 
IsrCStk 
IsrEntryTable 
IsrSrv 
_CoreFunc 
_CursorlSR 
_DEFAULT_PALET 
_DefaultCursor 
_DiTable 
_Module 
_NextDiEntry 
_PageFliplSR 
_TrapVector 
_WaitScanlSR 
_abort 

_addjnterrupt 
_add_module 
_atexit 

_bottom_of_stack 
_cjnt00 
_check_dpyint 
_clearjrame_buffer 
_clear_page 
jclear_screen 
jcommjnfo 
jconfig 
_cpacket 
_cpw 

_default_setup 
_del_all_modules 
jdeljnterrupt 
del module 



_delay 

_dm_clear_frame_buffer 

_dm_clearjDage 

_dm_clear_screen 

_dm_cpw 

_dm_get_nearest_color 

_dm_jget_palet 

_dm_jgsp2gsp 

_dm_init_palet 

jdmjmo 

_dmjDeek_breg 

_dm__poke_breg 

_dm_rmo 

_dm_set_bcolor 

_dm_set_clip_rect 

_dm_set_colors 

_dm_set_curs_shape 

_dm_set_cu rs_state 

_dm_set_fcolor 

_dm_set_palet_entry 

_dm_set_pmask 

_dm_set_ppop 

_dm_set_windowing 

_dm_set_wksp 

__end_of_dram 

_envcurs 

_envtext 

_env 

_exit 

_flush_extended 

Junctionjmplemented 

jgetjcolors 

jgetjconfig 
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_get_curs_state 


_palet 


_get_curs_xy 


jDalloc 


_jget_fontinfo 


_pattern 


_jget_isrj3riorities 


jDeek_breg 


_jget_module 


jDoke_breg 


_get_nearest_color 


jDut_vector 


_get_offscreen_memory 


_release_buffer 


jgetjDalet_entry 


_rmo 


_get_palet 


_set_bcolor 


jgetjDmask 


_set_clip_rect 


_jget_ppop 


_set_colors 


_get_state 
jgetjransp 


_set_config 
_set_curs_shape 


_jget_vector 


_set_curs_state 


_jget_windowing 


_set_fcolor 


_get_wksp 

jgetrev 

_gsp2gsp 

jgsp_calloc 

jgspjree 

jgsp_malloc 

jgsp_maxheap 

jgsp_minit 

jgsp_realloc 


_setjnterrupt 

_set_palet 

_setjDaIet_entry 

_setjDmask 

_setj3pop 

_set_windowing 

_set_wksp 

_setup 


JIlop 
Jnit_cursor 


_stack_size 
_start_of_dram 


Jnitjnterrupts 


_strcpy 


Jnit_palet 


_sys_free 


_init_text 


_sys_memory 


Jnit_trap_vectors 


_sysfont 


_init_video_regs 


_text_out 


Jmo 


_transp_off 


_main 


_transp_on 


_modeinfo 


_video_enabIe 


_monitorinfo 


_wait_scan 


_offscreen 


cinit 


J3age_busy 


edata 


jDageJIip 


end 


.page 


etext 
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C.3 TIGA Extended Primitive Symbols 

TIGA currently uses the following symbols in its extended primitives. Down- 
loadable extensions that work with the extended primitives should not use 
names that conflict with any of these symbols; this guarantee successful op- 
eration. 



arc_draw 


_dm_patnpenjDolyline 


_onarc 


arcjill 


_dmjDen_line 


_patn_line 


arc_pen 


_dm_pen_ovalarc 


_patnfill_convex 


arc_quadrant 


_dm_penjDiearc 


_patnfill_oval 


arc_quad 


_dm_penj3oint 


_patnfilljDiearc 


arc slice 


_dm_pen_polyline 


jDatnfill_polygon 


bitbit 


_dm_seed_fill 


jDatnfill_rect 


cJntOO 


_dm_seed_patnfill 


jDatnframe_oval 


config 


_dm_set_draw_origin 


_patnframe_rect 


deletejont 


_dm_setjDatn 


_patnpen_line 


dm_bitblt 


_dm_setjDensize 


jDatnpen_ovalarc 


dm_draw_line 


jdm_zoom_rect 


_patnpen_piearc 


dm_draw_oval 


_draw_eliparc 


_patnpenjDoint 


dm_draw_ovalarc 


_draw_line 


_patnpenjDolyline 


dm_draw_piearc 


_draw_ovalarc 


_pattern 


dm_draw_point 


_draw_oval 


_pen_eliparc 


dm_draw_polyline 


_drawjDiearc 


_pen_line 


dm_draw_rect 


_drawjDoint 


_pen_ovalarc 


dm_fill_convex 


_draw_polyline 


_penjDiearc 


dm_fill_oval 


_draw_rect 


_pen_point 


dm_fill_piearc 


_env 


_pen_polyline 


dmJilLpolygon 


_envtext 


_seed_fill 


dm_fill_rect 


_fill_convex 


_seed_patnfill 


dm_frame_oval 


_fill_eliparc 


_select_font 


dm_frame_rect 


JilLoval 


_set_draw_origin 


dm_getjDixel 


JilLpiearc 


_set_dstbm 


dm_patnfill_convex 


JilljDolygon 


_setjDatn 


dm_patnfill_oval 


JilLrect 


_setjDensize 


dm_patnfilljDiearc 


JilLshape 


_set_srcbm 


dm_patnfilljDolygon 


_frame_oval 


_set_textattr 


dm_patnfill_rect 


_frame_rect 


-Sinjbl 


dm_patnframe_oval 


_get_env 


_styled_line 


dm_patnframe_rect 


_get_pixel 


_swap_bm 


dm_patnpenjine 


_jget_textattr 


_sysfont 


dmjDatnpen_ovalarc 


_gsp_malloc 


_text_width 


dm_patnpenjDiearc 


_jgsp_realloc 


_zoom_rect 


dm_patnpen_point 


Jnstalljont 
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The TIGA-340 Software Porting Kit (SPK) contains all source required to 
port TIGA to any TMS340-based graphics board. The SPK is originally 
shipped with a Tl Software Development Board (SDB) compatible version 
of TIGA. This version is used as an example, and a port of TIGA to a different 
TMS340 board will involve modifications to the SDB port. 

Before beginning the porting process, make sure you have the following 
software tools installed on your system: 

Q Microsoft macro assembler, version 5.0 or above 

Q Microsoft MAKE utility 

Q Microsoft linker 

Ql TMS340 assembler/linker, version 3.0 or above 

Qi TMS340 C compiler, version 3.0 or above 

Porting TIGA consists basically of two tasks.The first is to modify the 
host-side TIGA code (the TIGA communication driver or CD for short). The 
second is to modify the TMS340-side code (the TIGA graphics manager or 
GM for short). Each of these tasks have well-defined, step-by-step proce- 
dures that make porting TIGA to a different TMS340-based board a relative- 
ly simple operation. Because the GM rebuilding process relies on afunction- 
al CD, you must first port the CD before porting the GM. 

Porting TIGA entails some knowledge of TIGA's architecture; therefore, it 
may be helpful to refer to Section 1 .3 for an overview of the components of 
TIGA. 

Section Page 

D.1 Porting the Communication Driver (CD) D-2 

D.2 Porting the Graphics Manager D-14 

D.3 Verifying Correct Operation D-21 

D.4 Debugging Your Port D-22 
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D.1 Porting the Communication Driver 

The TIGA communication driver (CD) is an MS-DOS Termi- 
nate-and-Stay-Resident (TSR) program that enables host communications 
with the TMS340-based board. When the TIGA-340 SPK Is Installed, It 
places all CD-specific files in the directory \t iga\cd. The files within this di- 
rectory that may need modifications, along with a description of each, are 
listed below: 

oemdata.asm Contains Information defining each mode of operation 
supported by the TMS340-based board 

oeminit . asm Contains board-specific initialization and inquiry functions 

setvideo . asm Contains routines to set/get video mode information 

sdbdefs.inc Contains hardware-specific equates 

Porting the TIGA CD involves modifications to each of the files above. The 
following four sections describe in detail these modifications. Note that all 
references to file names are assumed to be files within the \tiga\cd direc- 
tory unless otherwise noted. 

D.I .1 l\/lodifying the sdbd^f s . inc File 

The sdbdef s . inc file Contains general information describing the hardware 
aspects of the target TMS340-based board TIGA is being ported to. Before 
making any modifications to this file, first copy it to a file that will be used to 
describe your target board. Make sure to copy it within the \tiga\cd direc- 
tory and that its extension is . inc. For example purposes, assume the co- 
pied filename is newdef s . inc and use this filename throughoutthe commu- 
nication driver porting guide. 

Next, edit newdef s . inc; note that the file contains a number of equates de- 
fining constants that are used when the TIGA CD is rebuilt. Modify only 
the constants described below. Modifications to any constant not listed be- 
low will result in a non-functioning communication driver: 

OEMMSG This message is displayed when the CD is Installed. It de- 
scribes the board on which TIGA is running. Be sure to en- 
close the description within double quotes. 

SDB If your target board Is not the Tl Software Development Board 

(SDB), then set this constant to false (0). 

MEMORY This constant defines how the TMS340's host registers 
(HSTDATA, HSTCTRL, HSTADRH, and HSTADRL) are ac- 
cessed from the host. If your target board's host registers are 
memory-mapped, set this constant to 1 . Otherwise, they are 
l/0-mapped, in which case the constant should be set to 0. 
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SYSTEM If you want your TIGA CD to be compatible with Intel's 8086 
and later microprocessors, set this constant to false (0). If set 
to TRUE (1), 80x86 instructions will be used in the CD. This 
results in faster execution but places a restriction on the host 
processor type. 

Next, modify the host portion defining the host port locations. These equates 
define the host addresses (either memory or I/O) used to communicate with 
the TMS340. Note that these addresses are hard-coded. If your board can 
be configured to different host address memory locations, select one set of 
addresses for the initial port (refer to section D.1 .1 9 for more information on 
boards with multi-host port addressing). 

Note that the HSTSEG address is valid for memory-mapped host register 
boards only. Modify these constants to match your board's host register ad- 
dressing. 

The following values for the host register addresses are taken from the SDB 
(memory-mapped) port. 



HSTSEG 


Equ 


OCOOOh ; 


Host port seg. (mem-mapped only) 


HSTADRL 


Equ 


VEOOh ; 


Host address low 


HSTADRH 


Equ 


7F00h ; 


Host address high 


HSTDATA 


Equ 


7000h ; 


Host data 


HSTCTRL 


Equ 


7D00h ; 


Host control 



The next two equates are used as timeout values in the CD. For most ports, 
these values should suffice. However, if the call to gm_is_alive fails consis- 
tently, you may have to increase the GM_TIMEOUT value (see Section 
D.1.18 for more information). 

The next set of constants defines various monitors supported by the differ- 
ent operating modes of your board. Each monitor constant defines a bit flag 
in a 16-bit word. Therefore, TIGA supports up to 16 monitors per mode. 
The following monitor definitions were taken from the SDB port: 

NEC Equ 1 ; SDB port supports two monitors, the 
SONY Equ 2 ; NEC and the SONY Mult i syncs 

Here, two monitors are supported, the NEC Multisync and Sony Multisync. 
Note that the first monitor constant has a value of 01 h, and the next has a 
value of 02h. If additional monitors were supported, their values would be 
04h, 08h, 1 0h, etc., up to 80h. 

Next, modify the number of palette entries supported on your board in its de- 
fault power-up mode. The SDB uses the TMS34070 4-bit color palette and, 
therefore, has 16 palette entries. 

Finally, one miscellaneous equate may need modification for your port. 

STKSIZE-The host-side communication driver stack size may be modified 
to suit your needs. The SDB port allocates 0400h bytes of stack. 
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D.I .2 Modifying the oemdata . asm File 

The oemdata . asm file Contains descriptions of all the operating modes sup- 
ported by your board. An operating mode is defined as a given resolution 
with appropriate monitor timing values that support this resolution. The op- 
erating modes of the SDB port are used as an example. Use this example 
as a guide to define the operating modes of your board. 

The label Setup_Table defines the start of the operating mode specific data. 
The SDB port supports four operating modes: the first is a 640 X 480 X 4 reso- 
lution mode (1 display page) and the second is a 448 x 480 x 4 (2 display 
pages) mode. These two modes are duplicated for the NEC and Sony Multi- 
sync monitors. Each mode supported by your board must be defined by a 
label following the Setup_Entry label. These mode labels are used to actual- 
ly define the mode-specific data. 

; Define number of modes and mode/setup tables 



Setup_Table Equ This Word 

Setup_Entry Mode_640x480x4N 

Setup_Entry Mode_448x480x4N 

Setup_EntrY Mode_6 40x480x43 

Setup_EntrY Mode_4 48x480x43 



start of setup table 

SDB mode for NEC 

SDB mode 1 for NEC 

SDB mode for Sony. 

SDB mode 1 for Sony. 



D.I .3 Defining the !\/lode-Specific Information 

Each board operating mode has its own set of data describing the following 
items: 

Q Monitor identification flags 

Qk Mode-specific information 

Q Monitor timing information 

Qi Display page information 

i^ Offscreen memory information 

For example, mode of the SDB port is defined as follows: 
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SDB Mode 0: 640x480x4, 1 page for NEC Monitor 
*********************************************************************************** 



; SETUP Structure 



; Mode setup structure 



Mode_640x480x4N Equ This Byte 

Setup_Struc <NEC> 

Mode_Inf o lOOOh, 480, 640, 27, 20, 4, OFh, 4,PALET_ENTRIES, lOOh, 1, 2, OBOOh, lOOOh 

Monitor_Info OlBh, OlCh, OCCh, OCDh, OOlh, 018h, 01F8h, OlFAh, OFOlOh, 30, 

Page_Info OOOOOlOOh, OFFFCh 

Off_screen OOOOOBOOh, 640/4,480 

Off_Screen OOOOOD80h,160,480 

Off_Screen 001EOOOOh,1024,32 
EndjSetup 

Each operating mode of your board has a similar block of information de- 
fined, one block for eack mode defined in the Setup_Table. Use the follow- 
ing instructions to modify each mode information block for your board. 

D.I .4 Defining the Mode Label and Setup_Struc Structure 

The mode setup structure starts with a label identifying the mode. This label 
is the same as the one added In the Setup_Table entries earlier. 

Next, initialize the Setup_Struc macro with the valid monitors supported by 
this mode. These monitor constants were defined earlier in the 

newdef s . inc file. 



D.I .5 Defining the Mode_Struc Structure 

Next, modify the mode-specific information. The Modejnfo structure con- 
tains parameters describing this operating mode. The structure is defined 
in the file struct . inc as follows: 

Mode information structure 
Display pitch (bits) 
Vertical resolution (pixels) 
Horizontal resolution (pixels) 
Screen width (centimeters) 
Screen height (centimeters) 
Display pixel size 
Pixel mask 

Palette gun depth (bits) 
Palette size 

(For TMS34070 palette only) 
Number of screen pages 
Number of off-screen areas 
Temporary Workspace Address 
Temporary Workspace Pitch 
_ End of Mode_Struc structure 

The Mode_Num_Pages field describes the total number of display pages 
supported for this mode. Multiple display pages are used in TIGA to support 
animation via the page_flip function. Section D.1.7 provides additional in- 
formation. 



Mode_Struc 


St rue 


Mo de_D i sp_P it ch 


Dd? ; 


Mode_Disp_Vres 


Dw? ; 


Mode_D i sp_Hr e s 


Dw? ; 


Mode_Screen_Wide 


Dw? ; 


Mode_Screen_High 


Dw? ; 


Mo de_D i sp_P s i z e 


Dw? ; 


Mode_Pixel_Mask 


Dd? ; 


Mode_Palet_Gun_Depth 


Dw? ; 


Mo de_P a 1 e t_S i z e 


Dd? ; 


Mode_Palet_Inset 


Dw? ; 


Mode_Num_Pages 


Dw? ; 


Mode_Num_Offscrn 


Dw? ; 


Mo de_Wk sp_Addr e s s 


Dd? ; 


Mode_Wksp_Pitch 


Dd? ; 


Mode Struc 


Ends ; 
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The Mocle_Num_Offscrn field describes the total number of x-y offscreen 
memory blocl<s available for use by an application. Section D.1 .8 describes 
these memory blocks in greater detail. 

The fields Mode_Wksp_Address and Mode_Wksp_Pitch describe the off- 
screen workspace. This workspace is a 1 -bit-per-pixel bitmap with the same 
horizontal and vertical dimensions as the visible screen. It Is used by the 
fill_polygon and patnflll_polygon functions as a working buffer. If enough 
offscreen memory is available to support this workspace, then this offscreen 
memory block should be the first Off_Screen structure defined (see Section 
D.1 .8) and the Mode_Wksp_Address and Mode_Wksp_Pitch fields should 
be initialized to point to this block. 

D.1 .6 Defining the Monitorjnfo Structure 

Next, modify the Monitorjnfo specific data for this mode. This structure is 
defined in the struct . inc header file as follows: 

Monitor information structure 
End horizontal sync signal 
End horizontal blank signal 
Start horizontal blank signal 
Horizontal total (Characters) 
End vertical sync signal 
End vertical blank signal 
Start vertical blank signal 
Vertical total (Scanlines) 
Display control register 
Screen delay (Frames) 
Monitor type flags (BitO 
:0=color/ l=mono) Bits 1-15 
reserved 
_ End of Monitor_Struc structure 

The structure element, Monitor_Screen_Delay, specifies the delay (in 
frames) that the screen will be blanked when the video registers are loaded. 
This allows the monitor time to synchronize to the new timing values. 

The structure element Monitor_Flags specifies whether the monitor is color 
(when the LSB is a 0), or monochrome (when the LSB is 1 ). Bits 1 — 1 5 are 
eserved. The palette routines use this flag to choose between the intensity 
level or the R, G, B values specified in the palette structure. 

D.1 .7 Defining the Pagejnfo Structure 

The next structure, Pagejnfo, contains information defining the available 
display pages for this particular mode. Each mode must have at least 1 dis- 
play page defined. For each display page, a corresponding Pagejnfo 
structure must be defined. The actual number of display pages is defined 
in the Mode_Num_Pages field of the Mode_Struc structure. The Pagejnfo 
structure is defined in the file struct . inc as follows: 



Monitor_Struc 


St rue 


Monitor_Hesync 


Dw? ; 


Monitor Heblnk 


Dw? ; 


Monitor_Hsblnk 


Dw? ; 


Monitor_Htotal 


Dw? ; 


Monitor Vesync 


Dw? ; 


Monitor_Veblnk 


Dw? , 


Monitor_Vsblnk 


Dw? , 


Monitor_Vtotal 


Dw? , 


Monitor_Dpyctl 


Dw? , 


Monitor_Screen_Delay 


Dw? , 


Monitor_Flags 


Dw? , 


Monitor Struc 


Ends , 
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Page St rue 


St rue 






Page information structure 


Page_Base_Addr 


Dd 


•> 




Page base address 
(linear bit address) 


Page DpyStart 


Dw 


? 




Page start offset 


Page Pad 


Dw 


7 




Page dummy pad bytes 


Page_Struc 


Ends 






End of Page_Struc structure 



Each page is defined by two elements: 

1 ) The base address (loaded into the B-f lie register OFFSET) when this 
page is being written to 

2) The display start (loaded into the DPYSTRT I/O register) when this 
page Is being displayed 

Using Mode 1 (448 x 480 x 4, 2 pages) of the SDB port as an example, two 
display pages are supported. These page definitions are as follows: 

Page_Info 0000010 Oh, OFFFCh ; Page 
Page_Info 00000900h,0FFF4h ; Page 1 

The TIG A core function, page_f lip, enables the selection of the current dis- 
play and drawing page. For example, page_flip(0,1) selects page as the 
display page and page 1 as the drawing page. Therefore, B-file register 
OFFSET would be loaded with 0900h (the base address for page 1) and 
the DPYSTRT 10 register with OFFFCh (the display start for page 0). 

1 

Note: 

Even though the Pagejnfo structure contains 16 bits of pad, this value 
should not be entered as part of the Pagejnfo information. 



Be sure and note the maximum number of display pages defined in any op- 
erating mode of your board. This value is required when porting the TIGA 
graphics manager. 

D.I .8 Defining the Off_Screen Structure 

TIGA enables an application to use offscreen memory as a bitbit storage or 
temporary workspace though the get_offscreen_memory function. This 
function returns information describing the available offscreen memory 
areas that are defined in the OFF_SCREEN structure. 

The OFF SCREEN structure is defined in the file struct . inc as follows: 



Screen_Struc Struc 

Screen_Address Dd ? 

Screen_X_Ext Dw ? 

Screen_Y_Ext Dw ? 

Screen Struc Ends 



Screen information structure 
Start (linear) off-screen memory 
X extent of memory (pixels) 
Y extent of memory (pixels) 
End of Screen Struc structure 
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The actual number of offscreen areas for a particular mode is defined in the 
Mode_Num_Offscrn field of the Mode_Struc structure. For each offscreen 
area, a corresponding Off_Screen structure is defined. If your board does 
not contain any offscreen areas, then no off-screen structures need be de- 
fined. 

Using Mode of the SDB port as an example, 3 offscreen memory areas 
are available and are defined as follows: 

Off_Screen OOOOOBOOh, 640/4,480 ; Alloc. to offscrn wksp 
Off_Screen 00000D80h,160, 480 ; Offscreen area 1 
Off_Screen OOlEOOOOh, 1024,32 ; Offscreen area 2 

Note that the first Off_Screen blocl< defined is intended to be used for the 
offscreen workspace. The Mode_Wksp_Pitch and Mode_Wksp_Addrf ields 
of the Modejnfo structure for ModeO are initialized to point to this block. 

Be sure and note the maximum number of offscreen areas defined in any 
operating mode of your board. Thisvaluewill be required later when porting 
the TIGA graphics manager. 

D.I .9 Defining OEM-Specific Data 

If you have any other mode-specific data, it should be added to the operat- 
ing mode data using the OEM_Data structure. This structure, defined in the 
macro. inc file, follows the Off_Screen Structure data. To use the 
OEM_Data structure, modify the number of parameters expected by the 
OEM_Data macro in the macro. inc file. Then, supply the OEM-specific 
data using the OEM_Data macro. A corresponding change is required in the 
graphics manager portion of TIGA to support this new data. 

I I 

Note: 

In the SDB port, no OEM_Data Is defined, but an example of its usage is 
shown. 



D.I .1 Completing Modifications to oemdata . asm 

Repeat the above instructions to define all operating modes for your particu- 
lar board. 

After the last mode information block, global data variables used by the CD 
are declared. The Previous_Mode variable may require changing. This vari- 
able is used to store the TMS340 board emulation mode (that is, EGA, VGA) 
prior to loading TIGA. Because the SDB does not support emulations, the 
Previous_Mode is set to TIGA. However, If your board does support emula- 
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tlons, then initialize this variable to the emulation mode in which the board 
powers up. If the emulation is configurable by DIP switches, then an appro- 
priate function called within the oemjnit function (see Section D.1.11) 
should be written to initialize this variable. Valid constants for emulation 
modes are defined in the file \tiga\inciude\tiga.h file. 

Finally, the DRAM_Start and DRAM_End symbols need to be initialized to 
the largest block of DRAM on the target board. 

DRAM_End is used to store the high-water mark in memory where the sys- 
tem stack resides. The address should be double-word aligned and must 
not be higher than OFFFFDFEOh, since memory above this address is re- 
served in the TMS340 memory map. This address should also be equal to 
the bottom_of_stack value in the link control file of the graphics manager. 

D.1.11 Modifying the oeminit. asm File 

The oeminit . asm file Contains functions used to initialize a specific 
TIGA-compatible TMS340 target board. The functions in oeminit. asm 
shipped with the TIGA Software Porting Kit perform specific initializations 
for the SDB and therefore require modifications for your particular board. 

The oeminit . asmf lie Contains the following four board-specific initialization 
functions: 

OEMJnit Initializes the board. 

OEM_Sense Returns ID of current monitor in use. 

Monitorjnit initializes the TIGA mode table with all valid modes for cur- 
rent monitor in use. 

Video_Enable Switches video from EGA/VGA to TIGA. 

D.I .1 2 Modifying the OEMJnit Function 

TheOEMJnitfunction performs all initializations necessary to put the target 
TMS340-based board in a state where the TIGA graphics manager can be 
loaded to it. The TIGA communications driver calls the OEMJnit function 
when it is initially loaded. 

Using the SDB port as an example, the OEMJnit function first halts the 
TMS340, flushes the cache, and sets the INCR and INCW bits in the 
TMS340's HSTCTL register. It then switches on the SDB's shadow RAM, 
clears the interrupt enable I/O register so that the board TMS340 can be 
halted later, and clears the TMS340's CONTROL register. 

Note the comment within the OEMJnit function regarding the setting of the 
CONTROL register. It is extremely important to initialize the CONTROL 
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register properly to support the type of DRAM refresh cycles used on the 
board. 

I 
Note: 

Do not modify the code related to the high-water mark. 



D.I .1 3 Modifying ttie OEI\/l_Sense Function 

The OEM_Sense function is used to return the ID of thp monitor that is con- 
nected to the target TMS340-based board. The valid monitor IDs were pre- 
viously defined In the newdef s . inc file. 

In the SDB port, there Is no way to sense the type of monitor using the SDB. 
However, on other boards, DIP switches or monitor sense lines are avail- 
able for this purpose. This example function searches for a -s command 
line argument and sets dx to the Sony id if found. Othenwise, dx is set to 
NEC. 

D.I .14 l\/lodifying the i\/lonitorJnit Function 

The monltorjnit function calls OEM_Sense to get the current monitor con- 
nected to the target TMS340-based board. It then steps through the list of 
all modes defined in the Setup_Struc structures (defined in oemdata.asm) 
and puts the indices of those modes that support the current monitor into 
space allocated in Mode_Table (defined in oemdata . asm). This, in essence, 
defines the total number of modes available for the current monitor in use. 

This function requires no modifications except when more than 1 6 monitors 
are supported. 

D.I .1 5 !\/lodif ying the Video__Enable Function 

This function invokes a graphics manager function that does nothing on the 
SDB, because there is no EGA emulation implemented on the SDB. Vid- 
eo_Enable is shown here as an example of its implementation. If the video 
on your board can be switched directly from the host side, then modify this 
function to do so. Othenwise, as illustrated in the SDB port, call the 
Video_Enable graphics manager function to perform the video switch. 

D.I .16 l\/Iodifying the setvideo.asm File 

The two functions within setvideo.asm, set_videomode and 
get_videomode, require porting only for those TMS340-based boards 
which support other graphic modes (that is, EGA, VGA, etc.). Because the 
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SDB does not support any other graphics modes, comments are given with- 
in the setvideo . asm code to Offer Suggestions on alternative graphics 
mode support. 

D.1.17 Miscellaneous Communication Driver Porting Issues 

The following sections describe additional modifications that may be need- 
ed for porting the TIGA communications driver to your specific board. 

D.I .18 Default Timeout for gm_is_alive Function 

The file error . asm Contains the function gm_is_alive. The purpose of this 
function is to check if the TIGA graphics manager (the part of TIGA which 
runs on the TMS340-side) is alive and running. It does this by installing its 
own error trap, calling one of TIGA's core primitives, and then waiting a cer- 
tain period for the TIGA primitive to complete. If the function does not com- 
plete in the time allotted, the error handler is called and false (0) is returned, 
indicating a non-functioning graphics manager. 

The delay time is defined by the constant GM_TIMEOUT in the file 
newdef s . inc and is set in the SDB port to 0.5 seconds. This timeout value 
may have to be lengthened on those boards with monitor screen delays 
longer than 30 frames (see Defining the Monitorjnfo Structure in Section 
D.1.6). 

This potential problem is evident when an application calls a function requir- 
ing the use of TIGA's linking loader TIGALNK (that is, create_alm) immedi- 
ately following a call to set_videomode(TIG A, INITIALIZE). Because the 
call to set_videomode reloads the video timing registers (using the delay 
defined by the monitor delay amount), and tigalnk first checks if the TIGA 
graphics manager is alive (via gmjs_allve), there is a chance that this 
delay will cause gm_is_aiive to fail, tigalnk then returns an error mes- 
sage indicating that the ALM file could not be created (in this example). 

D.1.19 Using Boards with Multi-Addressable Host Port Locations 

TMS340-based boards with multi-addressable host port locations were 
mentioned in Section D.1.1. Because the host port addresses are hard- 
coded in the newdef s . inc file, Only one of the address sets are supported. 
However, by making some simple modifications, programmable host port 
addressing is possible. 

First, five 1 6-bit variables must be declared in the CD data section (in the 
file data. asm). These variables are 

HstCtrlAdr dw ? ; HSTCTRL host address 
HstAdrlAdr dw ? ; HSTADRL host address 
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HstAdrhAdr dw ? ; HSTADRH host address 
HstDataAdr dw ? ; HSTDATA host address 
HstSegAdr dw ? ; Segment address (memory map only) 

Next, these addresses must be initialized before any I/O is performed 
through the TMS340's host port. 

The file macro. inc Contains all the macros that perform I/O functions 
through the TMS340 host port. For example, Write_HSTDATA is a macro 
which writes 1 6 bits of data to the TMS340 HSTDATA register. For memory 
mapped boards, ax is assumed destroyed by these macros. For 1/0- 
mapped boards, ax and dx are assumed destroyed. Currently, these mac- 
ros assume hardcoded addresses for the host port locations. To modify the 
macros, use the following Write_HSTDATA example as a guideline: 

Write_HSTDATA Macro Reg, Seg 
Local SegReg 
Ifb <Seg> 
SegReg Equ <es> 

Else 
SegReg Equ <Seg> 
Endif 

push bx ; We must save bx (not assumed destroyed) 
mov bx,ds: HstDataAdr ; Load bx with address of HSTDATA 
If MEMORY 

Ifidni <Reg>,<bx> ; If reg passed == bx 
mov ax, Reg ; then copy to ax 
mov SegReg: [bx],ax ; and send it 
Else 

mov SegReg: [bx] , Reg ; otherwise, send the reg 
Endif 
Else 

Set_IO [bx] ; Set io address 

Ifidni <Reg>,<ax> ; If reg passed == ax 

out dx,ax ; then output ax 

Else 

mov ax, Reg ; otherwise, move reg to ax 
out dx,ax ; and output ax 

Endif 
Endif 

pop bx ; Restore bx 

Endm 

You must also search through each of the .asmfilesinthe \tiga\cd directo- 
ry and replace all occurrences of HSTSEG with the appropriate value in the 
HstSegAdr variable. 
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D.1 .20 Rebuilding the Communication Driver 

Rebuilding the TIG A communication driver is a simple operation. First, edit 
the file makecd.bat. This batch is designed to rebuild the communication 
driver for the SBD and must be modified for your board as follows: 

Step 1 : Change lines 3 and 4 to check for an id for your board. Also, 
change the label from SDB to a label for your board. 

Step 2: Change the label on line 7 to your new label. 

Step 3: Modify the description on line 1 0. 

Step 4: Change line 1 5 to copy newdef s . inc into def s . inc. 

After making the above modifications, enter makecd yourid from the 
MS-DOS command line from the \tiga\cd directory. Note that yoivr/c/isthe 
identification added to the makecd.bat batch file in step 1 above.This re- 
builds the TIGA communication driver tigacd . exe and copies it into TIGA's 
main directory \tiga. 
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D.2 Porting the Graphics Manager 

The TIGA Graphics Manager (GM) is the portion of TIG A that resides on the 
target graphics board (the TMS340 side). All files associated with the TIGA 
GM are installed in the \tiga\gm directory, with specific portions of the GM 
split into subdirectories under the \tiga\gm directory as follows: 

Directory Contents 

\tiga\gm TIGA graphics manager command executive 

\tiga\gm\corprims TIGA GM core primitives 

\taga\gm\extprims TIGA GM extended primitives 

\tiga\gm\sdb TIGA GM board-specific functions 

It is suggested that another directory be created underthe\tiga\gm directo- 
ry to contain board-specific functions for your particular board. For exam- 
ple, assume a directory called \tiga\gm\newgm exists and that all of the 
files from the \taga\gm\sdb directory have been copied into the 

\tiga\gm\newgm directory. 

The majority of the modifications necessary to port the TIGA GM are made 
to the board-specific functions in the \tiga\gm\newgm directory. 

The following sections describe In detail these modifications. Note that all 
references to filenames are assumed to be files within the \tiga\gin\newgm 
directory unless othenwise noted. 

The board-specific functions In the \tiga\gm\newgm directory are grouped 
into four main categories: 

Q Clearing video memory, 

Qi Palette-specific functions, 

Qi Configuration functions, and 

^ Miscellaneous functions. 

D.2.1 Video l\/!emory Initialization Functions 

ciearfrm.asm The clear_frame_buffer function uses the fastest possi- 
ble method to clear the entire frame buffer to a specified 
color. In the SDB port, shift register transfer cycles are 
used, if this is not possible on the target TMS340 board, 
use a FILL (see the clearjscreen function in the file 
ciearscr. asm for Information on how this is done). 

ciearpag . asm The clear_page function uses the fastest possible method 
to clear the entire current drawing page to a specified color. 
Because shift register transfers cannot be used to clear 
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only a portion of the entire frame buffer on the SDB, the 
SDB port simply calls the clear_screen function, which 
performs a FILL. The port of this function should use shift 
register transfers if possible. 

clear scr . asm The clear_screen function uses the fastest possible meth- 
od to clear the visible portion of the current drawing page to 
a specified color. Although this file is not grouped with the 
other board-specific, video memory initialization functions, 
it may be ported to utilize a faster screen clearing method. 
The SDB port uses the FILL instruction. 

D.2.2 Palette-Specific Functions 

The following functions provide the capability to utilize a color palette on the 
target board. The SDB board uses the TMS34070 color palette, and these 
functions are therefore written to use the TMS34070. They must be modi- 
fied if your board has a color palette other than the TMS34070. 

getpaiet . c The function get_palet returns the values in the global pal- 
ette array paiet stored in TMS340 memory. Generally, this 
function does not require any porting. 

initpaie . c The function init_palet sets the palette to EGA default col- 
ors. It should replicate these colors through the entire pal- 
ette. On the SDB, this is trivial since it has only1 6 entries. 
Where there are more entries, this will need to be done in a 
loop. If the palette is in ROM and no initialization is possi- 
ble, this function should not be implemented and its entry 
should be cleared in the \tiga\gin\primdef s. c file to in- 
sure functionjmpiemented returns false. 

setpaiet.asm The set_palet and set_palet_entry functions within 
setpaiet.asm perform initialization of a TI\/IS34070 pal- 
ette which stores the palette information in the frame buffer. 
Note that the data stored in the global array paiet (de- 
clared in oem.c) is the physical color. The LS 4 bits are 
masked because they are not used intheTMS34070. If the 
palette is in ROM and no initialization is possible, this func- 
tion should not be implemented and its entry should be 
cleared in the \tiga\gm\primdefs.c file to ensure 
functionjmpiemented returns false. 

Note that the paiet routines use the monitor_fiags field of the 
monit or_inf o Structure to determine if the monitor is color or monochrome. 
This field selects the use of eitherther,g,b values or the lvalue to initial- 
ize the paiet. 
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D.2.3 Configuration Functions 

config.c The get_config function does not require porting. The 

set_conflg function may require porting if your board re- 
quires specific initializations for a particular mode. This ini- 
tialization can be performed wherever convenient within 
the set_conflg function. 

An example of an initialization that may be required for your board involves 
adding support for OEM mode data specified in the Setup structure. If OEM- 
specific data was added to the oemdata . asm file during the CD port (via the 
OEM_Data structure, see Section D.1 .9), then the graphics manager por- 
tion of TIGA must be modified to support this data. Normally, the code to 
handle OEM-specific data is added to the set_config function. 

oem. h This file contains constants and type definitions used to ini- 

tialize and maintain mode information in the graphics 
manager. The constants VIDEO_MEMORY_START, 
VIDEO_MEMORY_END, and PALET_ENTRIES should 
be modified to match your board specifications. 
PALET_ENTRIES should contain the number of palette 
entries in your default board mode. The three shared 
memory constants, SHARED_MEM_SIZE, 

SHARED_HOST_ADDR, and SHARED_GSP_ADDR 
should be initialized to values other than if the board sup- 
ports shared memory. If it does not, (as in the SDB port), 
initialize to 0. 

The DRAM_RM_RR constant defines the DRAM refresh mode and refresh 
rate. It is ORed with TIGA's default CONTROL value to initialize the TMS340 
processor CONTROL register. The value of this constant in the SDB port, 
0x08, specifies RAS-oniy refresh (RR field = 0) and refresh to occur every 
64 local clock periods (RM field = 01 ). 

The communication buffers, used by TIGA to buffer commands between the 
host and the TMS340, are declared statically in TMS340 memory. The 
oem. h file contains two constants that define the size and number of these 
buffers. 

The NUM_COMM_BUFFERS constant defines the numberof communica- 
tion buffers. Each communication buffer contains the information for one 
command. Therefore, the more communication buffers defined, the more 
commands that can be queued. The recommended minimum is three com- 
munication buffers. 

The COMM_BUFFER_SIZE constant defines the size (in bytes) of the data 
area in each communication buffer. The value assigned to this constant 
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must be at least 1 K (1 024) bytes and a multiple of 2. This minimum size 
is necessary to ensure that data less than 1 024 bytes long can be sent to 
the TMS340 processor without fear of overflowing the communication buff- 
er. 

The MAX_PAGES and MAX_OFFSCREEN constants must be set to the 
maximum number of pages and offscreen areas, respectively, in any oper- 
ating mode defined in the communication driver port (see Section D.1.7, 
which defines the PAGEJNFO Structure and Defining the OFF_SCREEN 
structure for more information). This is to insure that there is sufficient 
memory allocated to download these structures to the GM. 

The HEADER and SETUP structures may require modification to support 
any OEM-specific data added to the CD port (via the OEM_Data structure, 
see Section D.1.9 for more information). 

oem . c This file contains the initial configuration and setup structures. 

The data contained in these default structures is used to ini- 
tialize the TIGA environment when the graphics manager is 
initially executed (that is, the GM banner message is dis- 
played), and also to statically define an area in TMS340 
memory where mode information from the host is down- 
loaded. This configuration is overwritten almost immediately 
thereafter by the current mode information downloaded by the 
host. The data in Default Modeinfo, Default Monitor info, De- 
fault Page and Default Offscreen should be initialized with one 
mode from the oemdata . asm file in the communication driver. 

In a future release of TIGA, the copying of the setup structure into a fixed 
length default structure may well be changed to use system heap, thereby 
enabling the setup structure to be dynamic in size. This initial configuration 
is also useful because it enables debug messages to be printed from the 
graphic manager's main loop during debug of the GM port. 



D.2.4 Miscellaneous Functions 



initvide . c The function Init_vicleo_regs initializes the video 

registers for the new mode. This function does not 
require porting unless the target board needs ini- 
tialization of some other board-specific latches re- 
lating to video timing. 

videnbi . c In the SDB port, the video_enable function does 

nothing. However, for a board that uses a separate 
frame buffer for alternate graphics modes (that is, 
EGA), the videojenable function switches the 
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back-end to display the frame bufferforthe correct 
mode. It is called by the host side function set_vi- 
deomode. 

sysf ont . asm Two system fonts are supplied with the TIGA port: 

sys640 . asm and sys1024 . asm. The former is de- 
signed for low resolution (640 by 480 and below), 
the latter for high resolution (1024 x 768 and 
above). To select a particular system font, copy It 
Into the file sysf ont . asm. This is the files that will 
actually be assembled and linked into the graphics 
manager when it Is rebuilt. 

trapvect .asm The functions within the trapvect .asm file per- 

form I/O with the TMS340 processor interrupt trap 
vectors. This file requires modifications if the inter- 
rupt traps for your board are located In ROM or are 
not contiguous in memory from TMS340 address 
OFFFFFCOO1 6 (trap 31 ) to OFFFFFFEO1 6 (trap 0). 

\tiga\gm\primdefs.c This file defines all implemented core functions 
provided by theTIGA graphics manager. The ad- 
dresses of functions that are not implemented in 
your specific board port should be cleared and 
their declarations removed to insurefunctionjm- 
plemented will return false for these functions. 
Consult the functionjmplemented description 
in Chapter 3 for a list of functions that are likely not 
to be implemented on all boards. 

\tiga\gm\gmdefs.c The Only modification required in the 
\tiga\gm\gmdefs.c file Is the pathname of the 
OEM-specific header include file (line 10). Modify 
the pathname of this file to include your OEM-spe- 
cific definitions. 

\tiga\gm\tigagm. inc The Include file \t iga\gm\tigagm. inc contains a 

label named OEMMSG as an Identifying string for 
your board. Modify the string to the name of the 
board being ported to. This message Is displayed 
when the graphics manager is executed. 

There are two possible modes of cursor operation In TIGA. The default 
mode (recommended method) is a display interrupt driven cursor. This en- 
tails the cursor being redrawn every frame, which is acceptable for most sys- 
tems. In very high resolution displays, however, the overhead of a display 
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interrupt cursor may be unacceptable, in which case a hide/show cursor 
mechanism may be used. To obtain a hide/show cursor, modify the value 
of NON_DLCURSORfromOto1. The lattercursorflashesquite noticeably, 
whereas the display interrupt cursor is solid. 

D.2.5 Rebuilding the Grapiiics Manager 

Rebuilding the TIGA graphics manager consists of four parts: 

1 ) Rebuilding the TIGA core primitives 

2) Rebuilding the TIGA extended primitives 

3) Rebuilding the board-specific functions 

4) Rebuilding the TIGA command executive 

The batch file \tiga\gin\makegm. bat does all of this automatically. Howev- 
er, since this batch file and all others associated with rebuilding the GM were 
designed for the SDB port, a few changes are required before rebuilding 
your GM port. 

\tiga\gm\makegm.bat 

This is the main batch file that rebuilds the TIGA 
GM. It is invoked from the DOS command line with 
one argument. 

The following SDB port dependencies may have to 
be modified: 

Q The batch file argument id of SDB 

Q The board-specific directory (\tiga\gm\sdb) 
and make file name (sdbiib.mak) 

I^ The board-dependent library filename 

(\tiga\gm\sdb\sdb . lib) 

Q Comments 

After building the GM, makegm.bat automatically attempts to create the new 
GM symbol file \tiga\tiga340.sym by first running tiga.cd and then 
tigaink /cs. It Is for this reason that the CD port should be completed prior 
to porting the GM. 

\tiga\gm\tigagm. cmd 

This is the link command file used by gspink. exeto 
build the TIGA graphics manager out file 

tigagm.out. 

The following SDB port dependencies may have to 
be modified: 
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Q The board-dependent library filename 

(\tiga\gm\sdb\sdb.lib) 

Q The values assigned to the labels: 
_start_of_dram 
_bottom_of_stack 
_stack_size 
_end_of_dram 

□i The values assigned to program: 
origin 
length 

□i Comments 



Note: 

The label _bottom_of_stack must be double-word (32-bit) aligned, (that is, 
the 5 LSBs must be zero) and must correspond to the address DRAM_End 
in the communication driver. See Section D.1 .10. 



\tiga\gm\tigagm.mak 

This make file rebuilds the GM command executive 
and links all portions of the GM to form the out file 

tigagm.out. 

The following SDB port dependency may have to be 
modified: 

The board-dependent library filename 

\tiga\gm\sdb\sdb.lib located in the liSt Of 

dependencies for tigagm. out. 

\tiga\gm\newgm\sdblib .mak 

This make file rebuilds the board-dependent library. 

The following SDB port dependencies may have to 
be modified: 

Q The filename of the make file itself 

Qi The filename of the board-dependent library 

(sdb.lib) 

After modifying the above files, change your current directory to \tiga\gm 
and enter: makegm yourid, where yourid is the board identifier you added 
to the makegm.bat batch file. The TIGA graphics manager is then built and 
the output file tigagm.out copied into the TIGA system directory \tiga. 

D-20 Porting TIGA 



Verifying Correct Operation 

D.3 Verifying Correct Operation 

Included with the TIGA SPK is a comprehensive test suite designed to test 
different aspects of a TIGA port. This test suite can be run from the 
\tigapgms\tests directory by entering tigatest from the DOS command 
line. 

It Is suggested that the tests be run in the order displayed on the menu and 
that problems be fixed as they are encountered. 

After verifying correct operation of the test suite, try some of the other test 
programs supplied in the tigapgms directory. 
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D.4 Debugging Your Port 



The TIGA communication driver can be easily debugged using Microsoft's 
CodeVlew(R) or comparable debugger. The TIGA graphics manager can 
be debugged by using your board's TMS340 debugger. The following are 
some suggestions for debugging the TIGA GM: 

The TIGA graphics manager initializes all TMS340 trap vectors upon star- 
tup. This can cause havoc with your debugger, which may initialize trap vec- 
tors (that is, for single-step capability) before loading and executing the 
TIGA GM. To overcome this problem, modify the init_trap_vectors func- 
tion in the file \tiga\gm\sdb\trapvect .asm SO that trap vectors used by 
your debugger are not overwritten. 

After displaying its startup message, the GM then waits for handshaking to 
occur with the host. If necessary, a host TIGA application should be written 
that performs the handshake with the TIGA GM as follows: 

finclude <tiga.h> 

main ( ) 

{ 

set_videomode (TIGA,NO_INIT) ; 

handshake ( ) ; 
} 

After performing the handshake, the GM command executive waits for a 
TIGA command from the host. 
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Appendix E 

Debugger Support for TIGA 



TIGA is the definitive interface standard for applications software written 
to run on the TMS340 architecture, but it gives no guidelines to developers 
of software with special hardware accessing requirements, such as debug- 
gers. 

A set of routines has been included in TIGA to meet the often unique needs 
of debugger developers. This appendix contains the initial TIGA debugger 
routines developed. 

Section Page 

E.1 TIGA Debugger Routines E-2 

E.2 Compatibility Functions E-12 
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E.1 TIGA Debugger Routines 

A separate document describing the use of tine debugger functions will be 
publisiied in the future. The debugger routines development will be based 
on the following criteria and on any user feedback received: 

1) Portable to any TIGA environment, which potentially includes all 
TMS3401 0- and TMS34020-based PC graphics displays. 

2) Transparent to share the TMS3401 0's host interface registers with an 
application being debugged that uses the host interface for communi- 
cation between host and TMS340 resident software. 

3) Able to support the symbolic debug of RLMs (Relocatable Load Mod- 
ules), if running in an environment where the TIGA graphics manager 
is active. 

The following is a list of the routines in TIGA that provide debugger support: 

Q get_vector: Get contents of GSP trap vector 

Qi set_vector: Set contents of GSP trap vector 

□i set_xstate: Set GSP execution state 

□i get_xstate: Get GSP execution state 

Q get_memseg: Get high/low bounds of GSP memory segment 

i^ set_memseg: Set high/low bounds of GSP memory segment 

Qi set_msg: Send a message to the GSP 

Qi get_msg: Receive a message from the GSP 

□k save_commstate: Save communication state 

Or rstr_commstate: Restore communication state 

Qi oemjnit: Initialize board-specific data 

I I 

Note: 

The get_vector and set_vector functions are described in Section 3.3 be- 
cause their usefulness is not restricted to debuggers. 
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Return High/Low Bounds of GSP Memory Segment get_memseg 

Syntax void get_meinseg( addrlo, addhi ); 

unsigned long *addrlo, *addrhi; 

Type Core 

Description The get_memseg function is not for general use. It is provided for use by 
debuggers and other such tools that have special hardware accessing re- 
quirements. This function returns the low and high bit addresses of a usable 
block of TMS340 memory. Note that if the TIGA graphics manager is active 
(determined by a call to gm_is_allve) then this block of memory has been 
appropriated by the TIGA memory manager, and should not be used. In- 
stead, a call to TIGA should be used to allocate usable memory. The two 
arguments, addrio and addrhi, are pointers to unsigned longs where the 
TMS340 addresses are to be placed. 
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get_msg Return a Message from the GSP 
Syntax unsigned short get_msg(); 

Type Core 

Description The get_msg function is not for general use. It is provided for use by debug- 
gers and other such tools that have special hardware accessing require- 
ments.This function receives a 3-bit message from the TMS340. The mes- 
sage is located in bits ^ 2 of the returned value. The fourth bit, bit 3, is 
an interrupt bit and indicates that an interrupt was requested by the host. 
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Return GSP Execution State get_XState 

Syntax unsigned short get_xstate () ; 

Type Core 

Description The get_xstate function is not for general use. It is provided for use by de- 
buggers and otiier sucii tools which have special hardware accessing re- 
quirements. This function returns the current TMS340 execution state. The 
returned 1 6 bits are described below: 



Oi BitO 1 

Q Bit1 1 

Oi Bit2 1 

Q Bits 1 

a Bit4 1 



f TMS340 is halted, if not. 
f NMI set, if not 
f NMIMODE set, if not 
f cache flushed, if not 
f cache disabled, if not 



Ql Bits 5—15 Reserved for future use 

Example #include <tiga.h> 
main ( ) 

{ 

if (cd_is_alive ) 
{ 

if (get_xstate & 1) 

printfC'GSP is halted\n") ; 
else 

printfC'GSP is running\n") , 
} 
} 
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rstr_COmmstate Restore Communication State 
Syntax unsigned short rstr_coitimstate() ; 

Type Core 

Description The rstr_commstate function is not for general use. It is provided for use 
by debuggers and other such tools that have special hardware accessing 
requirements. This function restores the state of TMS340 communications 
to the state it was in after a previous call to save_commstate.The function 
returns zero if unable to save the state, nonzero if it is successful. 
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Save Communication State save COmmstate 
Syntax unsigned short save_commstate() ; 

Type Core 

Description The save_commstate function is not for general use. It is provided for use 
by debuggers and otiier such tools that have special hardware accessing 
requirements. This function saves the state of TMS340 communications. 
The function returns zero if unable to save the state, nonzero if it is succes- 
sful. 
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Set_memseg Set High/Low Bounds of GSP Memory Segment 

Syntax void set_memseg (addrlo, addhi) ; 

unsigned long addrlo, addrhi; 

Type Core 

Description The set_memseg function is not for general use. It is provided for use by 
debuggers and other such tools that have special hardware accessing re- 
quirements. This function sets the low and high bit addresses of a usable 
block of TMS340 memory. It should be called after using some of the 
memory returned by get_memseg to reflect the new memory size. 
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Set a Message from the GSP set_msg 

SyntSX void set_msg ( msg ) ; 

unsigned short msg; 

Type Core 

Description The set_msg function is not for general use. It is provided for use by debug- 
gers and other such tools that have special hardware accessing require- 
ments. This function sends a 3 bit message to the TMS340. The message 
Is located in bits — 2 of argument msg. The fourth bit, bit 3, is an interrupt 
bit and requests a host interrupt Into the TMS340. 
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Syntax void set_xstate (options); 

unsigned short options; 

Type Core 

Description The set_xstate function Is not for general use. It is provided for use by de- 
buggers and other such tools which have special hardware accessing re- 
quirements. This function sets the current TMS340 execution state. The re- 
turned 16 bits are described below: 

Oi Bit 1 to halt the TMS340, to let it run 

Q Bit 1 1 to invoke an NMI, to clear NMI 

Q Bit2 1 to set NMIMODE, to clear NMI 

Q Bit 3 1 to flush cache, to stop cache flush 

Qi Bit 4 1 to disable cache, to enable cache 

Q Bits 1 — 1 5 Reserved for future use, must be set to Os 

Exampie #include <tiga.h> 
main ( ) 
{ 

if (cd_is_alive() ) 
{ 

set_xstate(l); /* halt the GSP */ 

set_xstate(0); /* run the GSP */ 

} 
} 
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Initialize Board-Specific Data oem_l n it 
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Syntax void oem_init ( ) 

Type Core 

Description This function fiaits tlie TI\/IS340 and performs any board-specific initializa- 
tion prior to loading a COFF file. 
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E.2 Compatibility Functions 



It Is recommended that the compatibility functions not be used by an appli- 
cation programmer. Their functions can be performed by the entry points in 
the previous section and by the communication functions described In 
Chapter 3. These functions talk directly to TMS34010 hardware, which Is 
not present on the TMS34020, and their functionality can be emulated only 
on the TMS34020. However, since the TMS34010 has been available for 
some years now, many utilities have been written that interface to the 
TMS34010 hardware directly. If these utilities are to be ported to TIGA, in 
the understanding that they may not run correctly on the TMS34020 or other 
future products, then these functions may provide aquick method of porting. 

read_hstacldr Read the TMS3401 host address register 

read_hstadrh Read the TMS3401 host address high register 

read.hstadri Read the TMS3401 host address low register 

read_hstctl Read the TMS3401 host control register 

read_hstdata Read the TMS3401 host data register 

write_hstaddr Write to the TMS3401 host address register 

write_hstadrh Write to the TMS3401 host address high register 

write_hstadrl Write to the TMS3401 host address low register 

write_hstcti Write to the TMS3401 host control register 

write_hstdata Write to the TMS3401 host data register 



E-12 



Debugger Support for TIGA 



Read the TMS34010 Host Address Register read_hstaddr 



Syntax unsigned long read_hstaddr ( ) ; 

Type Core 

Description This function returns the contents of the host address register of the 
TMS34010. 
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read_hStadrh Read the TMS34010 Host Address High Register 
Syntax unsigned short read_hstadrh() ;. 

Type Core 

Description This function returns tlie contents of the host address high register of the 
TMS34010. 



E-1 4 Debugger Support for TIGA 



Read the TMS34010 Host Address Low Register reaci_hstadrl 

Syntax unsigned short read_hstadrl() ; 

Type Core 

Description This function returns tiie contents of tlie iiost address low register of the 
TMS34010. 
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read_hstCtl Read the TMS34010Host Control Register 
Syntax unsigned short read_hstctl () ; 

Type Core 

Description This function returns the contents of the host control register of the 
TMS34010. 
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Read the TMS34010 Host Data Register read_hstdata 

Syntax unsigned short read._hstdata() ; 

Type Core 

Description This function returns the contents of the host data register of the TMS3401 0. 
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write_hstaddr Write to the TMS34010 Host Address Register 

Syntax void write_hstaddr (value) 

unsigned long value; 

Type Core 

Description This function writes tlie 32-bit value supplied into the host address register 
oftheTMS34010. 
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Write to the TMS34010 Host Address High Register write_hstadrh 

Syntax void write_hstadrh( value) 

unsigned short value; 

Type Core 

Description This function writes the 1 6-bit value supplied into the host address high reg- 
ister of the TMS3401 0. 
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write_hstadrl Write to the TMS34010 Host Address Low Register 

Syntax void writ e_hstadrl( value) 

unsigned short value; 

Type Core 

Description This function writes the 1 6-bit value supplied into the host address low reg- 
ister of the TMS3401 0. 
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Write to the TMS34010 Host Control Register wrlte_hstCtl 

Syntax void write_hstctl( value) 

unsigned short value; 

Type Core 

Description This function writes the 1 6-bit value supplied into the host control register 
of the TMS3401 0. Note that in order to function properly, TIGA expects the 
values of the INCR, INCW, and LBL bits in host control to be set in a particu- 
lar manner. If these bits are modified, they must be restored prior to invok- 
ing another TIGA function or the TIGA environment may be corrupted. 
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SyntSX void write_hstdata (value) 

unsigned short value; 

Type Core 

Description This function writes the 1 6-bit value supplied into the host data register of 
theTMS34010. 
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Appendix F 

Glossary 






ADI ™: Autodesk Device Interface, an interface specification used for de- 
veloping customized drivers for periplieral devices for Autodesl^ prod- 
ucts. 

A_DIR: An MS-DOS environment variable; identifies the directories 
searched when you specify include and macro files for the TMS340 fami- 
ly assembler. 

Al : Application Interface. A part of TIGA consisting of a linl<able applica- 
tion library and include files that reference TIGA type and function defini- 
tions. The Al provides the interface between an application and the TIGA 
communication driver (CD). 

ALM: Absolute Load Module, an extension to the TIGA standard in the 
form of TMS340 object code. It is linked to an absolute memory location 
and stored in a memory image format. An application can load the ALM 
to invoke custom TMS340 functions. 



bitbit: Bit aligned block transfer. Transfer of a rectangular array of pixel 
information from one location in a bitmap to another with potential of ap- 
plying 1 of 1 6 logical operators during the transfer. 

bitmap: 1. The digital representation of an image in which bits are 
mapped to pixels. 2. A block of memory used to hold raster images in a 
device-specific format. 



CD: Communication Driver. This is a terminate-and-stay-resident pro- 
gram that runs on the PC. It is specif ic to a particular board and is supplied 
by the board manufacturer with the board.The CD contains functions that 
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are invoked by an application's calls to the A! to communicate via the PC- 
bus to the target TMS340 board. 

C_DIR: An MS-DOS environment variable; it identifies the directories 
searched when you specify include files for the TMS340 C-compiler and 
when specifying object directories for the TMS340 linker. 

COFF: Common Object File Format. An implementation of the object file 
format of the same name developed by AT&T. The TMS340 family com- 
piler, assembler, and linker use and produce COFF files. 

command buffer: An area of TMS340 memory used by the TIGA-340 in- 
terface buffer data passed by the application and read by the TMS340 
processor. 

command number: An identifier of a function to be invoked by an appli- 
cation when the function resides on the TMS340 board. The command 
number consists of three parts: 1 ) The function type, which specifies the 
format that the parameters are referenced by the TMS340. 2) The mod- 
ule number, which acts as an identifier to the group of functions. Every 
DLM receives a module number when it is installed . 3) The function num- 
ber, which specifies the specific function within the DLM that is to be in- 
voked. 

communication buffer: See command buffer. 

configuration: The hardware setting of the TMS340 board, comprising 
display resolution, pixel size, palette size, availability of shared memory, 
etc. 

coprocessor: Microdevice that offloads numeric operations from the 
main processor to speed up overall operation. The TMS34082 is acopro- 
cessor to the TMS34020. The two devices are tightly coupled together. 
The coprocessor adds to the register and instruction capability of the 
TMS34020, resulting in improved handling of floating point arithmetic. In 
this manual, the TMS340 processors are occasionally defined as copro- 
cessors to the 80x86 PC processor. This is to emphasize that the 
TMS340 is a programmable processor and can offload much of the bur- 
den of the graphics processing and bitmap manipulation from the host 
PC. 

core primitives: A group of TIGA functions that can always be invoked 
by an application after TIGA has been Installed, as opposed to the ex- 
tended primitives, which need to be loaded explicitly by an application. 

C-pacl(et mode: A method of passing parameters in TIGA from the host 
to a function on the TMS340 board. It enables the parameters pushed 
onto the host stack to appear on the TMS340 program stack, as if the 
function had been invoked locally to the TMS340. 
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cursor: In TIGA, this refers to a graphics cursor, which is an icon on the 
screen. The cursor is generally under mouse control and is used as a 
pointing device in a graphics application. 



DDK: Driver Developer's Kit. A product provided by Texas Instruments to 
allow software developers to write application drivers that Interface to the 
TIGA-340 standard. It consists of aTlGAdriverforthe Texas Instruments 
software development board (SDB), the TIGA application interface (Al), 
and example programs. 

direct mode: A TIGA mode that is the fastest mechanism to transfer pa- 
rameters from the host to a function on the TMS340 board. The parame- 
ter data is passed in raw form to a TIGA communication buffer, and the 
TMS340 function receives a pointer to the data. 

DLM: Dynamic Load Module. The DLM is a key part of TIGA's extensibil- 
ity. The module consists of a collection of custom C or assembly routines 
that are not othenwise part of TIGA; thus, they are an extension of TIGA's 
functionality. The DLM is loaded by an application so that the custom 
TMS340 functions can be invoked by the application. There are two types 
of modules: Relocatable Load Modules (RLMs) and Absolute Load Mod- 
ules (ALMs). 



environment or drawing environment: A group of attributes consisting 
of drawing origin, pen size, fill pattern, source and destination bitmaps, 
and line style. 

environment variabie: An MS-DOS variable that can have a string as- 
signed by an end-user with the MS-DOS SETcommand. This string can 
be interrogated by a program running under MS-DOS. 

extended primitives: A portion of the TIGA interface functions that can 
be invoked on/y by a TIGA application after they have been explicitly in- 
stalled.They consist of mostly drawing primitives. 

extensibility: A key feature of TIGA consists of an expandable function 
set. An application programmer can write custom TMS340 functions, 
which can be installed at runtime and invoked from the host application 
in the same manner as the standard TIGA functions. 
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font: A set of characters in predefined format that contain alignment infor- 
mation, allowing the text routines to produce a visually correct represen- 
tation of a given character string. 

frame buffer: A portion of memory used to buffer rasterized data to be 
output to a CRT display monitor. The contents of the frame buffer are of- 
ten referred to as the bitmap of the display and contain the logical pixels 
corresponding to the points on the monitor screen. 



GM: Graphics Manager. A TMS340 object file specific to a particular 
board, supplied with the board by the manufacturer. It contains a com- 
mand executive to process commands sent from the application, and a 
set of primitives. Some of these are integral TIGA primitives and some 
may be user extensions. 

GSP: Graphics System Processor. A TMS340 family-based system with 
the processing power and control capabilities necessary to manage high- 
performance bitmapped graphics. 



heap: An area of memory that a program can allocate dynamically. 



ISR: Interrupt Service Routine. A routine to service an interrupt on the 
TMS340 processor. The most common interrupt is that produced by the 
display interrupt, but other interrupts are available from the host proces- 
sor and from two external interrupt pins for window violation. ISRs can 
be downloaded by an application as part of a DLM . 

ISV: Independent Software Vendor. A company that produces software 
products. In this guide it refers to a company that writes a software prod- 
uct to interface directly with TIGA. ISVs include Microsoft, Autodesk, etc. 



LIM ™: LIM expanded memory. This system was developed by Lotus, In- 
tel, and Microsoft, to define a hardware and software interface for 80x86 
processors running under MS-DOS. LIM provides access to bank- 
switched random access memory. 
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linking loader: A program called TIGALNK that runs under MS-DOS and 
is an integral part of TIGA. It loads and links a dynamic load module with 
user extensions to TIGA into the TIGA Graphics Manager on the 
TMS340. 



memory management: Also referred to as dynamic memory allocation. 
It consists of a group of functions that are used for heap management. 

mode: A particular configuration of aJDoard. An individual board may have 
several modes, for example: 1 024-pixels x 768-lines at 8 bits-per-pixel, 
or 640-pixels x 480-lines at 4 bits-per-pixel. 

MS-DOS ™: Microsoft Disk Operating System. A PC-based operating 
system. Because MS-DOS and PC-DOS are esentially the same operat- 
ing system, this manual uses the term MS-DOS to refer to both systems. 



NMI: Non-Maskable InterruptJhe NMI cannot be disabled; it is usually 
generated by a host processor. 



OEM: Original Equipment Manufacturer. A hardware manufacturing com- 
pany. In this user's guide, it refers to companies that manufacture PC 
graphics add-in boards with a TMS340 processor on them. 

offscreen memory: The part of the frame buffer not being output to a dis- 
play. A frame buffer, although typically one contiguous area of linear 
memory, can be viewed as a rectangular area with a specific pitch. Each 
row of the rectangular area corresponds to a row of pixels on the screen. 
If the length Is less than the frame buffer pitch, or if there are more lines 
in the frame buffer than are displayed on the screen, there will be an area 
of the frame buffer not used for display. This area is named offscreen 
memory. Offscreen memory does not include the program memory used 
to store code and data. 

origin: The zero intersection of X and Y axes from which all points are cal- 
culated. 
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page: Some TMS340 boards may have enough memory in their frame 
buffer to hold two complete copies of the bitmap output to the screen. This 
technique, sometimes called double buffering, allows one area of the 
screen to be displayed (the display page) while another is being updated 
(the drawing page). When the drawing is completed, the drawing and dis- 
play pages are interchanged (page flipping). The flip Is synchronized to 
the vertical blank time to ensure a flicker-free display. This technique is 
useful for producing animation sequences. 

palette: A digital-lookup table used in a computer graphics display for 
translating data from the bitmap into the pixel values shown on the dis- 
play. 

pattern or fill pattern: SomeTIGA graphics output primitives use a pen 
to fill an area with a pattern rather than a solid color. The pattern Is speci- 
fied as a 1 -bit-per-pixel map. When the pattern is drawn, Os in the bitmap 
are drawn using the current background color, and 1 s are drawn using 
the current foreground color. 

pen or drawing pen: SomeTIGA graphics output primitives use a pen to 
draw an outline. The drawing pen has application-selectable width and 
height. The area covered by the pen can be solid or pattern-filled. 

pixel processing|: A logical or arithmetic combination of two pixel values 
(source and destination). 

PixBIt: Pixel Block transfer. Operations on arrays of pixels in which each 
pixel is represented by one or more bits. PixBIt operations are a superset 
of bitbit operations and include not only commonly used logical opera- 
tions, but also integer arithmetic and other multi-bit operations. 

plane: (Also bit plane or color plane). A plane Is a bitmap layer in a display 
device with multiple bits per pixel. If the pixel size is n bits and the bits in 
each pixel are numbered Oto n-1, plane Is made up of bits from all 
the pixels, and the plane n-l is made up of bits numbered n-1 from all 
the pixels. A layered graphics display allows planes or groups of planes 
to be manipulated independently of the other planes. 



raster-op: See pixel processing. 

RLM: Relocatable Load Module. An extension to the TIG A standard In the 
form of TMS340 object code. The RLM file is in COFF file format. It is 
loaded by an application so that the application can invoke custom 
TMS340 functions. 
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SDB: Software Development Board. A PC-compatible board manufac- 
tured by Texas Instruments. The SDB contains a TMS34010 graphics 
processor. The two TIGA kits (DDK and SPK) produced by Texas Instru- 
ments use the SDB as their target board. 

SDK: Software Developer's Kit. A Texas Instruments product that allows 
software developers to write TMS340 code. The SDK may be used to de- 
velop a TIGA extension, but it is equally applicable for programmers who 
wish to develop stand-alone TMS340 applications. This kit contains the 
DDK and tools such as the C compiler, assembler, and linker. 

shift-register transfer: A transfer between RAM storage and the internal 
shift register in a video RAM. 

SPK: Software Porting Kit. A Texas Instruments product that allows man- 
ufacturers of TMS340-based boards to port TIGA to their board. It con- 
tains all TIGA software source code as well as the SDK. 

swizzle: The reversal of every bit in a byte. This is required to convertf rom 
big-endian processors (where the smallest numbered bit in a word is 
most significant), to little-endian processors (where the smallest num- 
bered bit in a word is least significant). 

symbol table: A file containing the symbol names of all the variables and 
functions on the TMS340 side of TIGA. The symbol table is used by the 
linking loader when it is downloading an RLM to resolve references to 
those symbols. This enables the functions in the RLM to call TIGA primi- 
tives that are resident on the TMS340 board. 



TIGA ™, TIG A-340 ™ : Texas Instruments Graphics Architecture . A soft- 
ware interface standard that allows a host processor to communicate 
with the TMS340 graphics processors that are typically resident on an 
add-in board. The current implementation of TIGA is for the PC market 
and interfaces the 80x86 processor running under MS-DOS with the 
TMS340. 

TIGACD: This Is the file name of the executable program containing the 
communication driver that you run to install TIGA on your system. 

TIGALNK: See linking loader. 

time-out: An application invokes a TIGA TMS340 function by placing a 
command number and appropriate parameters in one of several com- 
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mand buffers. After loading several commands, the command buffers 
may be full; the host has to wait until the TMS340 finishes the current 
command and frees up a buffer. Also, if the function invoked needs to re- 
turn data back to the application, the application must wait until the 
TMS340 completes the command. If the application waits longer than a 
specified time, a time-out warning message is displayed. 

TMS340: A family of graphics system processors and peripherals man- 
ufactured by Texas Instruments. 

TI\/IS3401 0: First-generation graphics processor manufactured by Texas 
instruments. 

TMS34020: Second-generation graphics processor manufactured by 
Texas Instruments. 

TMS34070: First-generation color palette manufactured by Texas Instru- 
ments. 

TMS34082: Floating-point unit manufactured by Texas Instruments; co- 
processor to the TMS34020. 

transparency: When a pixel with the attribute of transparency is written 
to the screen, it is effectively invisible, and does not alter that portion of 
the screen it is written to. For example, in a pixel array containing the pat- 
tern for the letter A, all pixels surrounding the A pattern could be given 
a special value indicating that they are transparent. When the array is 
written to the screen, the A pattern, but not the pixels in the rectangle con- 
taining it, would be invisible. 

trap vector: A specific 32-bit address in TMS340 memory that contains 
the address of an interrupt service routine. 

TSR: Terminate and Stay Resident. A type of program that runs under 
MS-DOS. When it terminates, this type of program leaves a portion of it- 
self in memory. 



window: A specified rectangular area of virtual space on the display. 

workspace: An area of memory that is equal in size to a 1-bit-per-pixel 
representation of the current display resolution. Polygon fill functions use 
the workspace as a temporary drawing area before drawing on the 
screen. The workspace can reside either in offscreen memory or in heap. 
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absolute load module, ALM, 3-12, 3-22, 

3-96, 4-2, 4-8, 4-48, 4-49 

installation, 4-8, 4-43 
application interface, Al, 1-4, 2-12, 3-2 

DDK, 2-5 

SPK, 2-5 
attributes, 3-5, 3-6, 3-9, 3-75, 3-76, 3-95, 

3-167, 3-179, 3-180, 4-33, A-7 




background color, 3-5, 3-55, 3-141 , 3-143, 

3-145,4-33 
bitbit, 3-8, 3-9, 3-14, 3-155, 3-166, 3-184, 

4-36 




C-packet, 4-10, 4-11,4-13, 4-18, 4-36, 4-41 

cc utility, 2-12 

cd_is_alive, 3-3, 3-16, 3-86 

cl,2-17 

clear functions, 3-4 

clear_frame_buffer, 3-4, 3-17 

clear_page, 3-4, 3-1 8, 3-1 9 

clear_screen, 3-4, 3-17, 3-18, 3-19 

citiga batch file, 2-12 

COFF loader, 3-86, 4-47 

comm_buff_size, 3-57, A-3 

comnnand buffer, 1-5, 3-3, 3-8, 3-35, 3-40, 

3-44, 3-57, 3-112, 3-118, 3-129, 3-135, 

4-12,4-13,4-16,4-18,4-36 



command number, 1-5, 3-103, 4-4, 4-10, 

4-11,4-13,4-36,4-43 
communication buffer. See command buffer 
communication driver, CD, 1-4, 2-5, 2-6, 

2-10, 2-11, 3-3, 3-8, 3-16, 4-12, 4-13, 

4-16,4-47 
communication functions, 1-4, 3-11 
compatibility functions, E-1 2 
CONFIG structure, 3-3, 3-6, 3-8, 3-10, 3-14, 

3-35, 3-40, 3-44, 3-57, 3-64, 3-66, 3-69, 

3-90, 3-108, 3-112, 3-118, 3-129, 3-135, 

3-144,4-13,4-16 

See also MODEINFO structure 
cop2gsp, 3-11,3-20 
coprocessor, 3-12, 3-20, 3-57, 3-81 
core primitives, 1-6, 2-5, 2-8, 3-2, 4-10, 4-11 , 

4-32, C-3 
cp_alt, 4-13, 4-14 
cp_cmd, 4-13, 4-14 
cp_ret, 4-1 3 
cpw, 3-5, 3-21 
create_alm, 3-12, 3-22, 3-159, 4-2, 4-8, 4-9, 

4-32, 4-43, 4-47 
create_esym, 3-12, 3-24, 4-32, 4-47 
current_mode, 3-57, 3-108, A-3 
cursor, 3-10, 3-59, 3-60, 3-90, 3-145, 3-146, 

3-152, 3-153, 4-33, 4-44, A-5 



debugger functions, E-2 
deletejont, 3-9, 3-26 
demonstrations and examples, 2-6 
device_rev, 3-57, A-3 
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debugger functions, E-2 

deletejont, 3-9, 3-26 

demonstrations and examples, 2-6 

device_rev, 3-57, A-3 

direct mode, 4-10, 4-11,4-12, 4-18,4-32, 

4-36, 4-41 
disp_hres, 3-58, A-11 
dispjDitcii, 3-14, 3-58, A-11 
dispjasize, 3-58, A-11, B-9 
disp_vres, 3-58, A-11 
display_mem_end, 3-57, A-4 
display_mem_start, 3-57, A-3 
dm_cmd, 4-18 
dmjpoly, 4-17,4-28 
dm_palt, 4-24 
dmjDcmd, 4-25, 4-41 
dmjDget, 4-23 
dmjDoly, 4-17, 4-26 
dmjDret, 4-25 
dm_psnd, 4-21 
dmjDStr, 4-24 
dm_ptrx, 4-24 
dm_ret, 4-20 

drawjine, 3-7, 3-27, B-2, B-7 
draw_oval, 3-7, 3-29, B-2, B-7 
draw_ovalarc, 3-7, 3-31 , B-2, B-7 
drawjDiearc, 3-7, 3-33, B-2, B-7 
drawjDoint, 3-7, 3-34, B-2, B-7 
drawjDolyline, 3-7, 3-8, 3-35, B-2, B-7 
draw_rect, 3-7, 3-37, B-2, B-7 
drawing origin, 3-6, 3-60, 3-61, 3-72, 3-142, 

3-145, 3-153, 3-154. A-6,B-5 
driver, 2-10 
driver developer's kit, DDK, 1-2, 2-4 

subdirectories, 2-5 

system requirements, 2-2 



environment variable, 2-11, 2-17, 3-22, 3-24, 

3-49, 3-61 , 3-96, 3-99, 3-101 , 4-7, 4-36, 

4-47 

autoexec modification, 2-9 
extended primitives, 2-5, 2-8, 3-2, 3-3, 3-50, 

3-99, 4-1 0, 4-11 , 4-43, B-1 , C-5 

DDK, 2-5 
extensibility, 1-3, 1-4, 1-6, 3-12, 3-22, 3-24, 

3-49, 3-50, 3-63, 3-90, 3-96, 3-99, 3-101, 

3-159,4-1 



field_extract, 3-11 , 3-16, 3-38, 4-32 
fieldjnsert, 3-11 , 3-16, 3-39, 4-32 
fill_convex, 3-7, 3-8, 3-40, B-2, B-6 
filLoval, 3-7, 3-42, B-2, B-6 
filljDiearc, 3-7, 3-43, B-2, B-6 
fill_polygon, 3-7, 3-8, 3-44, 3-80, 3-174, B-2, 

B-6 
filLrect, 3-7, 3-48, B-2, B-6 
floating point, 2-6, 4-40, 4-41 
floating point coprocessor. See coprocessor 
flush_esym, 3-12, 3-49, 4-32 
flush_extended, 3-12, 3-50, 4-32 
font, 2-13, 3-9, 3-26, 3-62, 3-95, 3-97, 3-140, 

3-145, 3-179, 3-180, A-7 
FONTINFO structure. See font 
foreground color, 3-5, 3-55, 3-143, 3-145, 

3-158,4-33 
frame_oval, 3-7, 3-51 , B-2 
frame_rect, 3-7, 3-52, B-2 
functionjmplemented, 3-3, 3-6, 3-20, 3-53, 

3-69, 3-70, B-9 



ENVIRONMENT structure, 3-5, 3-61, 3-145, 
4-33, A-6 



get_colors, 3-5, 3-55 

get_config, 3-3, 3-35, 3-57, 3-64, 3-90, 

3-112, 3-118, 3-129, 3-135, 3-144, 4-13, 

4-16 
get_curs_state, 3-10, 3-59 
get_curs_xy, 3-1 0, 3-60 
get_env, 3-5, 3-61 , 3-1 75 
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getjontinfo, 3-9, 3-62 
getJsrjDriorities, 3-12, 3-63, 3-96, 3-101, 

3-159,4-32,4-44,4-45 
geLmodeinfo, 3-3, 3-57, 3-64, 3-144, 4-32, 

A-11 
get_nearest_coIor, 3-6, 3-65, B-9 
get_offscreen_memory, 3-11, 3-58, 3-66, 

3-174,A-12,A-14 
get_palet, 3-6, 3-69, B-9 
getjDalet_entry, 3-6, 3-69, 3-70 
getjDixel, 3-10, 3-72 
get_pmask, 3-5, 3-73, 3-164 
getjDpop, 3-5, 3-74, 3-164 
getjextattr, 3-9, 3-75 
getjransp, 3-5, 3-76 
get_vector, 3-11,3-77 
get_videomode, 3-3, 3-78, 3-171, 4-32 
get_windowing, 3-5, 3-79 
get_wksp, 3-8, 3-44, 3-80 
graphics manager, GM, 1-5, 2-5, 2-10, 3-3, 

3-8, 3-1 6, 3-24, 3-86, 3-96, 3-1 01 , 4-1 4, 

4-32, 4-35, 4-44, 4-47, 4-49 
graphics output functions, 3-7, B-2 
graphics utility functions, 3-1 
gsp_calloc, 3-11,3-85 
gsp_execute, 3-3, 3-16, 3-86, 3-106 
gspjree, 3-11,3-87 

gsp_malloc, 3-11, 3-66, 3-88, 3-162, 3-174 
gsp_maxheap, 3-11 , 3-89 
gsp_minit, 3-11 , 3-57, 3-90 
gsp_realloc, 3-1 1 , 3-91 
gsp2cop, 3-11,3-53, 3-81 
gsp2gsp, 3-11,3-82 
gsp2host, 3-11 , 3-16, 3-83, 4-32 
gsp2hostxy, 3-11, 3-16, 3-84, 4-32 



include files, 2-5, 2-8, 2-9, 2-18, 4-11 , 4-14, 

4-32, 4-43, A-1 
initjDaiet, 3-6, 3-53, 3-94, B-10 
initjext, 3-9, 3-95 
initialization, 2-10, 3-3, 3-90, 3-94, 3-95, 

3-145,4-46,4-49 
install_alm, 3-12, 3-63, 3-96, 3-159, 4-3, 4-9, 

4-11,4-32,4-43,4-47 
installjont, 3-9, 3-95, 3-97 
install_primitives, 3-3, 3-12, 3-99, 4-10, 4-32 
instalLrIm, 3-12, 3-24, 3-63, 3-101, 3-159, 

4-3, 4-7, 4-11 , 4-32, 4-38, 4-45, 4-47 
install_usererror, 3-3, 3-4, 3-35, 3-41 , 3-45, 

3-103, 3-113, 3-119, 3-129, 3-135, 3-168, 

3-171,4-32 
installation, 2-4, 4-7, 4-38, 4-44 
interrupt, 2-6, 2-11, 3-12, 3-63, 3-79, 3-96, 

3-1 01 , 3-1 59, 3-1 73, 4-2, 4-4, 4-5, 4-32, 

4-33, 4-35, 4-44, 4-45, 4-46 



lib, 2-17 

link, 2-17 

linking loader, 1-5, 2-10, 3-22, 3-24, 3-49, 

4-1,4-2,4-9,4-47 
Imo, 3-10, 3-105 
loadcoff, 3-3, 3-16, 3-86, 3-106 



host2gsp, 3-11 , 3-16, 3-92, 4-32 
host2gspxy, 3-11 , 3-16, 3-93, 4-32 



make, 2-6, 2-12, 2-17, 4-38 

math/graphics, 1 -2, 2-1 2, 2-1 3 

memory management, 3-2, 3-11 , 4-2, A-3 

mg2tiga utility, 2-1 3 

MODEINFO structure, 3-3, 3-57, 3-64, 

3-144, A-11 
MONITORINFO structure, A-1 3 
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num_mocies, 3-57, A-3 
num_offscrn_areas, 3-58, 3-66, A-12 
num_pages, 3-58, 3-108, A-12 



offscreen, 3-4, 3-18, 3-19, 4-33, A-12, A-14 



page, 3-4, 3-10, 3-18, 3-58, 3-107, 3-108, 

3-144, 4-33, A-12 
PAGE structure, A-1 5 
page_busy, 3-10, 3-107 
pagejiip, 3-10, 3-108, A-1 5 
PALET structure, A-1 6 
palet_gun_depth, 3-6, 3-58, A-11 , B-9 
paletjnset, 3-58, A-12 
palet_size, 3-58, 3-69, A-1 2 
palette, 3-6, 3-18, 3-65, 3-69, 3-70, 3-94, 

3-160, 3-161, A-11, A-1 6, B-9 
patnfilLconvex, 3-7, 3-8, 3-112, B-2, B-4, B-6 
patnfilLoval, 3-7, 3-114, B-2, B-4, B-6 
patnfill_piearc, 3-7, 3-115, B-2, B-4, B-6 
patnfilljDolygon, 3-7, 3-8, 3-118, B-2, B-4, 

B-6 
patnfilLrect, 3-7, 3-120, B-2, B-4, B-6 
patnframe_oval, 3-7, 3-121, B-2, B-4 
patnframe_rect, 3-7, 3-122, B-2, B-4 
patnpenjine, 3-7, 3-123, B-2, B-4, B-8 
patnpen_ovalarc, 3-7, 3-126, B-2, B-4, B-8 
patnpenjDiearc, 3-7, 3-127, B-2, B-4, B-8 
patnpenjDoint, 3-128, B-2, B-4, B-8 
patnpenjDolyline, 3-7, 3-8, 3-129, B-2, B-4, 

B-8 
pattern, 3-5, 3-6, 3-7, 3-61, 3-112, 3-114, 

3-115, 3-118, 3-120, 3-121, 3-122, 3-123, 

3-126, 3-127, 3-128, 3-129, 3-139, 3-145, 

3-162, 4-33, A-6, A-1 7, B-2, B-4 
PATTERN structure. See pattern 
peek_breg, 3-10, 3-130 



pen, 3-6, 3-7, 3-61, 3-123, 3-126, 3-127, 
3-128, 3-129, 3-131, 3-132, 3-133, 3-134, 
3-135, 3-145, 3-163, A-6, B-2, B-8 

penjine, 3-7, 3-131 , B-2, B-8 

pen_ovalarc, 3-7, 3-132, B-2, B-8 

penjDiearc, 3-7, 3-133, B-2, B-8 

penjDoint, 3-7, 3-1 34, B-2, B-8 

penjDolyline, 3-7, 3-8, 3-135, B-2, B-8 

pixel array function, 3-8 

pixelmask, 3-58, A-11 

pixel processing, 3-5, 3-74, 3-76, 3-145, 
3-146, 3-165, A-5 

plane mask, 3-5, 3-73, 3-1 45, 3-1 64 

poke_breg, 3-10, 3-136 

poly drawing functions, 3-8, 4-16, B-2, B-6, 
B-8 

porting TIGA, D-1 

program_mem_end, 3-57, A-3 

program_mem_start, 3-57, A-3 



register usage, 4-33 

relocatable load module, RLM, 3-22, 3-101, 

4-2, 4-5, 4-38, 4-48, 4-49 

installation, 4-7 
rmo, 3-10,3-137 




screen_high, 3-58, A-11 
screen_wide, 3-58, A-11 
seedjill, 3-7, 3-66, 3-138 
seed_patnfill, 3-7,3-139 
selectjont, 3-9,3-140 
set_bcolor, 3-5, 3-141 
set_clip_rect, 3-5, 3-14, 3-142 
set_colors, 3-5, 3-143 
set_config, 3-3, 3-144, 4-32, A-3 
set_curs_shape, 3-10, 3-90, 3-146, A-5 
set_curs_state, 3-10, 3-152 
set_curs_xy, 3-10, 3-146, 3-153, A-5 
set_draw_origin, 3-5, 3-61, 3-154, A-6, B-5 
set_dstbm, 3-8, 3-14, 3-61 , 3-155, A-6 
setjcolor, 3-5, 3-1 58, A-7 
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setjnterrupt, 3-12, 3-159, 4-44, 4-45 
set_palet, 3-6, 3-53, 3-69, 3-160, B-9 
seLpalet_entry, 3-6, 3-53, 3-69, 3-161, B-9 
setjDatn, 3-5, 3-162, A-17 

See also pattern 
setjDensize, 3-5, 3-123, 3-163, A-6 

See also pen 
setjDmask, 3-5, 3-73, 3-164 
setjDpop, 3-5, 3-74, 3-165 
set_srcbm, 3-8, 3-14, 3-61 , 3-166, 3-184, 

A-6 
setjextattr, 3-9, 3-167, 3-179, A-10 
set_timeout, 3-3, 3-4, 3-168, 4-32 
setjransp, 3-5, 3-53, 3-169, 3-181, 3-182 
set_vector, 3-11,3-170 
set_videomode, 2-10, 3-3, 3-16, 3-78, 3-145, 

3-171,4-32,4-38,4-43 
set_windowing, 3-5, 3-79, 3-173 
set_wksp, 3-8, 3-44, 3-66, 3-80, 3-90, 3-118, 

3-174 
share_gsp_addr, 3-57, A-4 
share_host_addr, 3-57, A-4 
share_mem_size, 3-57, A-4 
software developer's kit, SDK, 1 -2 
software porting kit, SPK, 1-2, 2-4 

subdirectories, 2-5 

system requirements, 2-2 
stack_size, 3-57, 3-90, A-4 
styledjine, 3-7, 3-61, 3-175, A-6 
swap_bm, 3-8, 3-177 
symbol table, 3-12, 3-24, 3-49, 3-50, 4-2, 

4-48, 4-49 
synchronize, 3-3, 3-4, 3-178, 4-32, 4-40 
syntax and programming examples, 2-18 
sysjiags, 3-20, 3-57, 3-81 , A-3 
system requirements, 2-2 




text, 2-13, 3-9, 3-26, 3-62, 3-75, 3-95, 3-97, 

3-140, 3-167, 3-179, 3-180, 4-33, A-7 
text_out, 3-9, 3-167, 3-179 
text_width, 3-9, 3-167, 3-180 
TIGAEXT section, 3-96, 3-101 , 4-4, 4-5, 

4-11 , 4-13, 4-38, 4-39, 4-45, 4-47 
TIGAISR section, 4-4, 4-5, 4-44, 4-45, 4-47 
TIGALNK, 1-5, 2-10, 3-22, 3-24, 3-49, 4-1, 

4-2, 4-9, 4-47 
TIGAMODE utility, 2-6, 2-16, 3-3 
transp_off, 3-5, 3-181 
transp_on, 3-5, 3-182 
transparency, 3-5, 3-53, 3-76, 3-145, 3-169, 

3-181,3-182,4-33 
trap vector, 3-11 , 3-77, 3-170 



utilities, 2-5, 2-12, 2-17, 3-3, 3-10 



version_number, 3-57, A-3 



wait_scan, 3-10, 3-183 
windowing, 3-6, 3-79, 3-142, 3-145, 3-173 
wksp_addr, 3-58, 3-80, 3-174, A-12 
wkspjDitch, 3-58, 3-80, 3-174, A-12 
workspace, 3-8, 3-44, 3-58, 3-66, 3-80, 
3-118, 3-174 



zoom_rect, 3-8, 3-66, 3-184 
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TI Worldwide 
Sales Offices 



ARIZONA: Phoenix: 8825 N. 23rd Ave,, Ptioenix, 
AZ 85021, (602) 995-1 007;TUCS0N: 818 W. Miracle 
Mile, Suite 43, Tucson, AZ 85705, (6021 292-2640. 

CALIFORNIA: Irvina: 17891 Cartwrlght Dr., Irvine, CA 
92714, (714) 660-1200; Rossvilla: 1 Sierra Gate 
Plaza, Roseville, CA 95678, (916) 786-9208; 
San Di«ga: 4333 View Ridge Ave., Suite 100, 
San Diego, CA 92123, 1619) 278-9601; 
Santa Clara: 5353 Betsy Ross Dr., Santa Clara, CA 
95054, (408) 980-9000: Torranca: 690 Knox St.. 
Torrance, CA 90502, 1213) 217-7010; 
Woodland Hills: 21220 Erwin St., Woodland Hills. 
CA 91367, (818) 704-7759. 



CONNECTICUT: Wallingford: 9 Barnes Industrial Park 
Rd., Barnes Industrial Park, Wallingford, 
CT 06492, (2031 269-0074. 

FLORIDA: Altamonta Spring*: 370 S. North Lake Blvd, 

Altamonte Springs, FL 32701 , (305) 260-21 16; 

Ft. Lauderdale: 2950 N.W. 62nd St., 

Ft. Lauderdale, FL 33309, (305) 973-8502; 

Tampa: 4803 George Rd., Suite 390, 

Tampa, FL 33634, (813) 885-7411. 

GEORGIA: Norcroaa: 5515 Spalding Drive, Norcross, 
GA 3O092, (404) 662-7900 

ILLINOIS: Ariington Heights: 515 W. Algonquin. 
Arlington Heights, IL 60005, (312) 640-2925. 

INDIANA: Ft. Wayne: 2020 Invirood Dr.. 
Ft. Wayne, IN 46815, (219) 424-5174; 
Carmal: 550 Congressional Dr., Carmel. IN 46032. 
(317) 573-6400. 

IOWA: Cedar Rapids: 373 Collins Rd. NE, Suite 201. 
Cedar Rapids. lA 52402. (3191 395-9550. 



MICHIGAN: Farmingtan HiUs: 33737 W. 12 Mile Rd.. 
Farmington Hills. Ml 48018. (313) 553-1569. 
Grand Rapids: 3075 Orchard Vista Dr. S.E.. 
Grand Rapids. Ml 49506. 1616) 957-4200. 



NEW JERSEY: Iselin: 485E U.S. Route 1 South. 
Parkway Towers, Iselin, NJ 08830 (201) 750-1050. 

NEW MEXICO: Albuquerqua: 2820-D Broadbent Pkwy 
NE, Albuquerque, NM 87107, (505) 345-2555. 

NEW YORK: East Syracuae: 6365 Collamer Dr.. 
East Syracuse, NY 13057, (315) 463-9291; 
MelvRle: 1895 Walt Whitman Rd., P.O. Box 2936, 
Melville. NY 11747, (516)454-6600; 
Pittsford: 2851 Clover St., Pittsford, NY 14534, 
(716) 385-6770; 

Poughkeepaie: 385 South Rd.. Poughksepsie, 
NY 12601. (914) 473-2900. 

NORTH CAROLINA: ChariotM: 8 Woodlawn Green. 
Woodlawn Rd.. Charlotte, NC 28210, 1704) 
527-0933; Raleigh: 2809 Highwoods Blvd., Suite 100. 
Raleigh, NC 27625, (919) 876-2725. 

OHIO: Beachwood: 23775 Commerce Park Rd.. 
Beachwood, OH 44122. (216) 464-6100; 
Beavercnek: 4200 Colonel Glenn Hwy.. 
Beavercreek. OH 45431. (513) 427-6200. 



OREGON: Baaverton: 6700 SW 105th St.. Suite 110, 
Beaverton, OR 97005, (503) 643-6758. 



PUERTO RICO: Hato Ray: Mercantil Plaza BIdg., 
Suite 505, Hato Rey, PR 00918, (809) 753-8700. 

TENNESSEE: Johnson City: Erwin Hwy, 
P.O. Drawer 1255, Johnson City, TN 37605 
(615)461-2192. 

TEXAS: Austin: 12501 Research Blvd., Austin, TX 
78759, (512) 250-7655; Richardson: 1001 E. 
Campbell Rd., Richardson, TX 75081, 
(214) 680-5082; Houston: 9100 Southwest Frwy., 
Suite 250, Houston, TX 77074, (713) 778-6592; 
San Antonio: 1 000 Central Parkway South, 
San Antonio, TX 78232, (512) 496-1779. 

UTAH: Murray: 5201 South Green St., Suite 200. 
Murray. UT 84123, 1801) 266-8972. 



CANADA: Nspean: 301 Moodie Drive, Mallorn Center, 

Nepean, Ontario, Canada, K2H9C4, 

(613) 726-1970. Richmond Hill: 280 Centre St. E.. 

Richmond Hill L4C1B1, Ontario, Canada 

(416) 884-9181; St. Laurent: Ville St. Laurent 

Quebec, 9460 Trans Canada Hwy., St. Laurent, 

Quebec, Canada H4S1R7, (514) 336-1860. 



ARGENTINA: Texas Instruments Argentina Viamonte 
1119, 1053 Capital Federal, Buenos Aires, Argentina, 
541/748-3699 

AUSTRALIA (& NEW ZEALAND): Texas Instruments 
Australia Ltd.: 6-10 Talavera Rd., North Ryde 
(Sydney), New South Wales, Australia 21 13, 
2 -^ 887-1122; 6th Floor, 418 St. Kilda Road, 
Melbourne, Victoria, Australia 3004, 3 + 267-4677; 
171 Philip Highway, Elizabeth, South Australia 5112, 
8 + 255-2066. 

AUSTRIA: Texas Instruments Ges.m.b.H.: 
Industriestrabe B/16, A-2345 Brunn/Gebirge, 
2236-846210. 

BELGIUM: Texas Instruments N.V. Belgium S.A.: 11, 
Avenue Jules Bondetlaan 11, 1140 Brussels, Belgium, 
(02) 242-3080. 

BRAZIL: Texas Instruments Electronicos do Brasil 
Ltda.: Rua Paes Leme, 524-7 Andar Pinheiros, 05424 
Sao Paulo, Brazil, 0815-6166. 



FINLAND: Texas Instruments Finland OY: 
Ahertajantie 3, P.O. Box 81 , ESPOO, Finland, (90) 
0-461-422. 

FRANCE: Texas Instruments France: Paris Office, BP 
67 8-10 Avenue Morane-Saulnier, 78141 Velizy- 
Villacoublay cedex (1) 30 70 1003. 

GERMANY (Fed. Republic of Gemianyl: Texas 
Instruments Deutschland GmbH: Haggertystrasse 1, 
8050 Freising, 8161 -t- 80-4591; Kurfuerstendamm 
195/196, 1000 Berlin 15, 30-f882-7365; III, Hagen 
43/Kibbelstr8sse, .19, 4300 Essen, 201-24250; 
Kirchhorsterstrasse 2, 3000 Hannover 51, 
51 1 -^ 648021 ; Maybachstrabe 11, 7302 Ostfildern 
2-Nelingen, 711 -f 34030. 



Texas 
Instruments 



HONG KONG: Texas Instruments Hong Kong Ltd., 8th 
Floor, World Shipping Ctr., 7 Canton Rd., Kowloon, 
Hong Kong, 18521 3-7351223. 

IRELAND: Texas Instruments (Ireland) Limited: 
7/8 Harcourt Street, Stillorgan, County Dublin, Eire, 
1 781677. 

ITALY: Texas Instruments Italia S.p.A. Divisione 
Semiconduttori: Viale Europe, 40, 20093 Cologne 
Monzese (Milano), (02) 253001 ; Via Castello della 
Magliana, 38, 00148 Roma, (06) 5222651; 
Via Amendola, 17, 40100 Bologna, 1051) 554004. 

JAPAN: Tokyo Marketing/Sales (Headquarters): 
Texas Instruments Japan Ltd., MS Shibaura BIdg., 9F, 
4-13-23 Shibaura, Minato-ku, Tokyo 108, Japan, 
03-769-8700. Texas Instruments Japan Ltd.: Nissho- 
Iwai BIdg. 5F, 30 Imabashi 3-chome, Higashi-ku, 
Osaka 541, Japan, 06-294-1881; Daini Toyota West 
BIdg. 7F, 10-27 Meieki 4-chome, Nakamura-ku, 
Nagoya 450, 052-583-8691; Daiichi Seimei BIdg. 6F, 
3-10 Oyama-cho, Kanazawa 920, Ishikawa-ken, 
0762-23-5471; Daiichi Olympic Tachikawa Bidg. 6F, 
1-25-12 Akebono-cho, Tachikawa 190, Tokyo, 
0425-27-6426; Matsumoto Showa BIdg. 6F, 2-1 1 
Fukashi 1-chome, Matsumoto 390, Nagano-ken, 
0263-33-1060; Yokohama Nishiguchi KN BIdg. 6F, 
2-8-4 Kita-Saiwai-cho, Nishi-ku, Yokohama 220, 
045-322-6741; Nihon Seimei Kyoto Yasaka BIdg. 5F, 
843-2 Higashi Shiokohjidori, Nishinotoh-in Higashi-iru, 
Shiokouji, Shimogyo-ku, Kyoto 600, 075-341-7713; 
2597-1 , Aza Harudai, Oaza Yasaka, Kitsuki 873, Oita- 
ken, 09786-3-321 1; Miho Plant, 2350 Kihara Miho- 
mura, Inashiki-gun 300-04, Ibaragi-ken, 
0298-85-2541 . 

KOREA: Texas Instruments Korea Ltd., 28th Fl., Trade 
Tower, #1 59, Samsung-Dong, Kangnam-ku, Seoul, 
Korea 2-e 551-2810. 

MEXICO: Texas Instruments de Mexico S. A.: Alfonso 
Reyes— 115, Col. Hipodromo Condesa, Mexico, D.F., 
Mexico 06120, 525/525-3860. 

MIDDLE EAST: Texas Instruments: No. 13, 1st Floor 
Mannai BIdg., Diplomatic Area, P.O. Box 26335, 
Manama Bahrain, Arabian Gulf, 973 -f 274681. 

NETHERLANDS: Texas Instruments Holland B.V.. 
19 Hogehilweg, 1 100 AZ Amsterdam— Zuidoost, 
Holland 20 -f 5602911. 

NORWAY: Texas Instruments Norway A/S: PB106, 
Refstad 0585, Oslo 5, Norway, 12) 155090. 

PEOPLES REPUBLIC OF CHINA: Texas Instruments 
China Inc., Beijing Representative Office, 7-05 Citic 
BIdg., 19 Jianguomenwai Dajje, Beijing, China, (861) 
5002255, Ext. 3750. 

PHILIPPINES: Texas Instruments Asia Ltd.: 14th Floor, 
Ba- Lepanto BIdg., Paseo de Roxas, Maksti, Metro 
Manila, Philippines, 817-60-31. 

PORTUGAL: Texas Instruments Equipamento 
Electronico (Portugal), Lda.: Rua Eng. Frederico Ulrich, 
2650 Moreira Da Mala, 4470 Maia, Portugal, 
2-948-1003. 

SINGAPORE (-1- INDIA, INDONESIA, MALAYSIA. 
THAILAND): Texas Instruments Singapore (PTE) Ltd.. 
Asia Pacific Division, 101 Thompson Rd. #23-01. 
United Square. Singapore 1130, 350-8100. 



SWEDEN: Texas Instruments International Trade 
Corporation (Sverigefilialen): S-164-93, Stockholm, 
Sweden, 8 - 752-5800. 

SWITZERLAND: Texas Instruments, Inc., Reidstrasse 
6, CH-8953 Dietikon IZuerich) Switzerland, 
1-740 2220. 

TAIWAN: Texas Instruments Supply Co., 9th Floor 
Bank Tower, 205 Tun Hwa N. Rd., Taipei, Taiwan. 
Republic of China, 2 + 713-9311. 

UNITED KINGDOM: Texas Instruments Limited: 
Manton Lane, Bedford, MK41 7PA, England, 0234 
270111. 



TI Sales Offices 



ALABAMA: Huntsvllle (205) 837-7530. 

ARIZONA: Phoenix (602) 995-1007; 
Tucson (602) 292-2640. 

CALIFORNIA: Irvine (714) 660-1200; 
Rosevllle (916) 786-9206; 
San Diego (619) 278-9601; 
Santa Clara (408) 980-9000; 
Torrance (213) 217-7010; 
Woodland Hills (818) 704-7759. 

COLORADO: Aurora (303) 368-8000. 

CONNECTICUT: Walllngford (203) 269-0074. 

FLORIDA: Altamonte Springs (305) 260-21 16; 
Ft. Lauderdale (305) 973-8502; 
Tampa (813) 885-7411. 

GEORGIA: Norcross (404) 662-7900. 

ILLINOIS: Arlington Heights (312) 640-2925. 

INDIANA: Carmel (317) 573-6400; 
Ft. Wayne (219) 424-5174. 

IOWA: Cedar Rapids (319) 395-9550. 

KANSAS: Overland Park (913) 451-4511. 

MARYLAND: Columbia (301) 964-2003. 

MASSACHUSETTS: WaKham (617) 895-9100. 

MICHIGAN: Farmlngton Hills (313) 553-1569; 
Grand Rapids (616) 957-4200. 

MINNESOTA: Eden Prairie (612) 828-9300. 

MISSOURI: SL Louis (314) 569-7600. 

NEW JERSEY: Iselln (201 ) 750-1 050. 

NEW MEXICO: Albuquerque (505) 345-2555. 

NEW YORK: East Syracuse (315) 463-9291; 
Melville (516) 454-6600; 
Plttsford (716) 385-6770; 
Poughkeepsle (914) 473-2900. 

NORTH CAROLINA: Charlotte (704) 527-0933; 
Raleigh (919) 876-2725. 

OHIO: Beachwood (216) 464-6100; 
Beaver Creek (51 3) 427-6200. 

OREGON: Beaverton (503) 643-6758. 

PENNSYLVANIA: Blue Bell (215) 825-9500. 

PUERTO RICO: Hato Rey (809) 753-8700. 

TENNESSEE: Johnson City (615) 461-2192. 

TEXAS: Austin (512) 250-7655; 
Houston (713) 778-6592; 
Richardson (214) 680-5082; 
San Antonio (512) 496-1779. 

UTAH: Murray (801) 266-8972. 

WASHINGTON: Redmond (206) 881-3080. 

WISCONSIN: Brookfleld (414) 782-2899. 

CANADA: Nepean, Ontario (613) 726-1970; 
Richmond Hill, Ontario (416) 884-9181; 
St. Laurent, Quebec (514) 336-1860. 



TI Regional 
Technology Centers 

CALIFORNIA: Irvine (714) 660-8105; 
Santa Clara (408) 748-2220; 

GEORGIA: Norcross (404) 662-7945. 

ILUNOIS Arlington Heights (312) 640-2909. 

MASSACHUSETTS: Waltham (617)895-9196. 

TEXAS: Rtehardson (214) 680-5066. 

CANADA: Nepean, Ontario (613) 726-1970. 



TI Distributors 



TI AUTHORIZED DISTRIBUTORS 
Arrow/Klerulff Electronics Group 
Arrow (Canada) 
Future Electronics (Canada) 
GRS Electronics Co., Inc. 
Hail-Mark Electronics 
Marshall Industries 
Newark Electronics 
Schweber Electronics 
Time Electronics 
Wyle Laboratories 
Zeus Components 

-OBSOLETE PRODUCT ONLY- 
Rochester Electronics, Inc. 
Newburyport, Massachusetts 
(508) 462-9332 



ALABAMA: Arrow/Kierulff (205) 837-6955; 
Hall-Mark (205) 837-8700; Marshall (205) 881-9235; 
Schweber (205) 895-0480. 

ARIZONA: Arrow/Klerulff (602) 437-0750; 
Hail-Mark (602) 437-1200; Marshall (602) 496-0290; 
Schweber (602) 431-0030; Wyle (602) 866-2888. 

CALIFORNIA: Los Angeles/Orange County: 

Arrow/Kierulff (818) 701-7500, (714) 838-5422; 

Hail-Mark (818) 773-4500, (714) 669-4100; 

Marshall (818) 407-0101, (818) 459-5500, 

(714) 458-5395; Schweber (818) 880-9686; 

(714) 863-0200, (213) 320-8090; Wyle (818) 880-9000, 

(714) 863-9953; Zeus (714) 921-9000; (818) 889-3838; 

Sacramento: Hail-Mark (916) 624-9781; 

Marshall (916) 635-9700; Schweber (916) 364-0222; 

Wyle (916) 638-5282; 

San Diego: Arrow/Klerulff (619) 565-4800; 

Hall-Mark (619) 268-1201; Marshall (619) 578-9600; 

Schweber (619) 450-0454; Wyle (619) 565-9171; 

San Francisco Bay Area: Arrow/Kierulff (408) 745-6600, 

Hall-Mark (408) 432-0900; Marshall (408) 942-4600; 

Schweber (408) 432-7171; Wyle (408) 727-2500; 

Zeus (408) 998-5121. 

COLORADO: Arrow/Klerulff (303) 790-4444; 
Hall-Mark (303) 790-1662; Marshall (303) 451-8383; 
Schweber (303) 799-0258; Wyle (303) 457-9953. 

CONNETICUT: Arrow/Kierulff (203) 265-7741; 
Hail-Mark (203) 271-2844; Marshall (203) 265-3822; 
Schweber (203) 264-4700. 

FLORIDA: Ft Lauderdale: 

Arrow/Klerulff (305) 429-8200; Hall-Mark (305) 971-9280; 
Marshall (305) 977-4880; Schweber (305) 977-7511; 
Orlando: Arrow/Kierulff (407) 323-0252; 
Hall-Mark (407) 830-5855; Marshall (407) 767-8585; 
Schweber (407) 331-7555; Zeus (407) 365-3000; 
Tampa: Hail-Mark (813) 530-4543; 
Marshall (813) 576-1399; Schweber (813) 541-5100. 

GEORGIA: Arrow/Kierulff (404) 449-8252; 
Hall-Mark (404) 447-8000; Marshall (404) 923-5750; 
Schweber (404) 449-9170. 

ILLINOIS: Arrow/Klerulff (312) 250-0500; 
Hall-Mark (312) 860-3800; Marshall (312) 490-0155; 
Newark (312) 784-5100; Schweber (312) 364-3750. 

INDIANA: Indianapolis: An'ow/Klerulff (317) 243-9353; 
Hall-Mark (317) 872-8875; Marshall (317) 297-0483; 
Schweber (317) 843-1050. 

IOWA: Arrow/Kierulff (319) 395-7230; 
Schweber (319) 373-1417. 

KANSAS: KansasClty: Arrow/Kierulff (913) 541-9542; 
Hall-Mark (913) 888-4747; Marshall (913) 492-3121; 
Schweber (913) 492-2922. 



Texas 
Instruments 



MARYLAND: An-ow/Klerulff (301) 995-6002; 
Hall-Mark (301) 988-9800; Marshall (301) 235-9464; 
Schweber (301) 840-5900; Zeus (301) 997-1118. 

MASSACHUSETTS Arrow/Klerulff (508) 658-0900; 
Hall-Mark (508) 667-0902; Marshall (508) 658-0810; 
Schweber (617) 275-5100; Time (617) 532-6200; 
Wyle (617) 273-7300; Zeus (617) 863-8800. 

MICHIGAN: Detroit: Arrow/Kierulff (313)462-2290; 
Hall-Mark (313) 462-1205; Marshall (313) 525-5850; 
Newark (313) 967-0600; Schweber (313) 525-8100; 
Grand Rapids: Arrow/Klerulff (616) 243-0912. 

MINNESOTA: Arrow/Klerulff (612) 830-1800; 
Hail-Mark (612) 941-2600; Marshall (612) 559-2211; 
Schweber (612) 941-5280. 

MISSOURI: St. Louis: Arrow/Klerulff (314) 567-6888; 
Hall-Mark (314) 291-5350; Marshall (314) 291-4650; 
Schweber (314) 739-0526. 

NEW HAMPSHIRE: Arrow/Klerulff (603) 668-6968; 
Schweber (603) 625-2250. 

NEW JERSEY: Arrow/Kierulff (201) 538-0900, 
(609) 596-8000; GRS Electronics (609) 964-8560; 
Hall-Mark (201) 575-4415, (201) 882-9773, 
(609) 235-1900; Marshall (201 ) 882-0320, 
(609) 234-9100; Schweber (201) 227-7880. 

NEW MEXICO: Arrow/Klerulff (505) 243-4566. 

NEW YORK: Long Island: 

Arrow/Kienilff (516) 231-1009; Hall-Mark (516) 737-0600; 

Marshall (516) 273-2424; Schweber (516) 334-7474; 

Zeus (914) 937-7400; 

Rochester: Arrow/Klerulff (716) 427-0300; 

Hall-Mark (716) 425-3300; Marshall (716) 235-7620; 

Schweber (716) 424-2222; 

Syracuse: Marshall (607) 798-1611. 

NORTH CAROLINA: Arrow/Klerulff (919) 876-3132, 
(919) 725-8711; Haii-Mark (919) 872-0712; 
Marshall (919) 878-9882; Schweber (919) 876-0000. 

OHIO: Cleveland: Arrow/Klerulff (216) 248-3990; 
Hall-Mark (216) 349-4632; Marshall (216) 248-1788; 
Schweber (216) 464-2970; 
Columbus: Hall-Mark (614) 888-3313; 
Dayton: Arrow/Klerulff (513) 435-5563; 
Marshall (513) 898-4480; Schweber (513) 439-1800. 

OKLAHOMA: Arrow/Kierulff (918) 252-7537; 
Schweber (918) 622-8003. 

OREGON: Arrow/Klerulff (503) 645-6456; 
Marshall (503) 644-5050; Wyle (503) 640-6000. 

PENNSYLVANIA: Arrow/Kierulff (412) 856-7000, 
(215) 928-1800; GRS Electronics (215) 922-7037; 
Marshall (412) 963-0441 ; Schweber (215) 441-0600, 
(412)963-6804. 

TEXAS: Austin: Arrow/Kierulff (512) 835-4180; 

Hail-Mark (512) 258-8848; Marshall (512) 837-1991; 

Schweber (512) 339-0088; Wyle (512) 834-9957; 

Dallas: Arrow/Klerulff (214) 380-6464; 

Hall-Mark (214) 553-4300; Marshall (214) 233-5200; 

Schweber (214) 661-5010; Wyle (214) 235-9953; 

Zeus (214) 783-7010; 

El Paso: Marshall (915) 593-0706; 

Houston: Arrow/Kierulff (713) 530-4700; 

Hall-Mark (713) 781-6100; Marshall (713) 895-9200; 

Schweber (713) 784-3600; Wyle (713) 879-9953. 

UTAH: Arrow/Kierulff (801) 973-6913; 

Hall-Mark (801) 972-1008; Marshall (801) 485-1551; 

Wyle (801) 974-9953. 

WASHINGTON: Arrow/Klerulff (206) 575-4420; 
Marshall (206) 486-5747; Wyle (206) 881-1150. 

WISCONSIN: Arrow/Klerulff (414) 792-0150; 
Hall-Mark (414) 797-7844; Marshall (414) 797-8400; 
Schweber (414) 784-9020. 

CANADA: Calgary: Future (403) 235-5325; 

Edmonton: Future (403) 438-2858; 

Montreal: Arrow Canada (514) 735-5511; 

Future (514) 694-7710; 

Ottawa: Arrow Canada (613)226-6903; 

Future (613) 820-8313; 

Quebec City: Arrow Canada (418) 871-7500; 

Toronto: Arrow Canada (416) 672-7769; 

Future (416) 638-4771; Marshall (416) 674-2161; 

Vancouver: Arrow Canada (604) 291-2986; 

Future (604) 294-1166. 



Customer 
Response Center 

TOLL FREE: (800) 232-3200 

OUTSIDE USA: (214)995-6611 

(8;0Oa.m. - 5:00 p.m. CST) 
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